1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
6 <title>Documentation Guidelines</title>
7 <meta name="GENERATOR" content=
8 "Modular DocBook HTML Stylesheet Version 1.79">
9 <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
10 <link rel="PREVIOUS" title="The CVS Repository" href="cvs.html">
11 <link rel="NEXT" title="Coding Guidelines" href="coding.html">
12 <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
13 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
16 <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
17 "#840084" alink="#0000FF">
18 <div class="NAVHEADER">
19 <table summary="Header navigation table" width="100%" border="0"
20 cellpadding="0" cellspacing="0">
22 <th colspan="3" align="center">Privoxy Developer Manual</th>
26 <td width="10%" align="left" valign="bottom"><a href="cvs.html"
27 accesskey="P">Prev</a></td>
29 <td width="80%" align="center" valign="bottom"></td>
31 <td width="10%" align="right" valign="bottom"><a href="coding.html"
32 accesskey="N">Next</a></td>
35 <hr align="left" width="100%">
39 <h1 class="SECT1"><a name="DOCUMENTATION" id="DOCUMENTATION">3.
40 Documentation Guidelines</a></h1>
42 <p>All formal documents are maintained in Docbook SGML and located in the
43 <samp class="COMPUTEROUTPUT">doc/source/*</samp> directory. You will need
44 <a href="http://www.docbook.org" target="_top">Docbook</a>, the Docbook
45 DTD's and the Docbook modular stylesheets (or comparable alternatives),
46 and either <span class="APPLICATION">jade</span> or <span class=
47 "APPLICATION">openjade</span> (recommended) installed in order to build
48 docs from source. Currently there is <a href="../user-manual/index.html"
49 target="_top"><i class="CITETITLE">user-manual</i></a>, <a href=
50 "../faq/index.html" target="_top"><i class="CITETITLE">FAQ</i></a>, and,
51 of course this, the <i class="CITETITLE">developer-manual</i> in this
52 format. The <i class="CITETITLE">README</i>, <i class=
53 "CITETITLE">AUTHORS</i>, <i class="CITETITLE">INSTALL</i>, <i class=
54 "CITETITLE">privoxy.1</i> (man page), and <i class="CITETITLE">config</i>
55 files are also now maintained as Docbook SGML. These files, when built,
56 in the top-level source directory are generated files! Also, the
57 <span class="APPLICATION">Privoxy</span> <tt class=
58 "FILENAME">index.html</tt> (and a variation on this file, <tt class=
59 "FILENAME">privoxy-index.html</tt>, meant for inclusion with doc
60 packages), are maintained as SGML as well. <span class=
61 "emphasis"><i class="EMPHASIS">DO NOT edit these directly</i></span>.
62 Edit the SGML source, or contact someone involved in the
65 <p><tt class="FILENAME">config</tt> requires some special handling. The
66 reason it is maintained this way is so that the extensive comments in the
67 file mirror those in <i class="CITETITLE">user-manual</i>. But the
68 conversion process requires going from SGML to HTML to text to special
69 formatting required for the embedded comments. Some of this does not
70 survive so well. Especially some of the examples that are longer than 80
71 characters. The build process for this file outputs to <tt class=
72 "FILENAME">config.new</tt>, which should be reviewed for errors and
73 mis-formatting. Once satisfied that it is correct, then it should be hand
74 copied to <tt class="FILENAME">config</tt>.</p>
76 <p>Other, less formal documents (e.g. <tt class="FILENAME">LICENSE</tt>)
77 are maintained as plain text files in the top-level source directory.</p>
79 <p>Packagers are encouraged to include this documentation. For those
80 without the ability to build the docs locally, text versions of each are
81 kept in CVS. HTML versions are also being kept in CVS under <tt class=
82 "FILENAME">doc/webserver/*</tt>. And PDF version are kept in <tt class=
83 "FILENAME">doc/pdf/*</tt>.</p>
85 <p>Formal documents are built with the Makefile targets of <samp class=
86 "COMPUTEROUTPUT">make dok</samp>, or alternately <samp class=
87 "COMPUTEROUTPUT">make redhat-dok</samp>. If you have problems, try both.
88 The build process uses the document SGML sources in <samp class=
89 "COMPUTEROUTPUT">doc/source/*/*</samp> to update all text files in
90 <samp class="COMPUTEROUTPUT">doc/text/</samp> and to update all HTML
91 documents in <samp class="COMPUTEROUTPUT">doc/webserver/</samp>.</p>
93 <p>Documentation writers should please make sure documents build
94 successfully before committing to CVS, if possible.</p>
96 <p>How do you update the webserver (i.e. the pages on privoxy.org)?</p>
100 <p>First, build the docs by running <samp class="COMPUTEROUTPUT">make
101 dok</samp> (or alternately <samp class="COMPUTEROUTPUT">make
102 redhat-dok</samp>). For PDF docs, do <samp class=
103 "COMPUTEROUTPUT">make dok-pdf</samp>.</p>
107 <p>Run <samp class="COMPUTEROUTPUT">make webserver</samp> which
108 copies all files from <samp class=
109 "COMPUTEROUTPUT">doc/webserver</samp> to the sourceforge webserver
114 <p>Finished docs should be occasionally submitted to CVS (<tt class=
115 "FILENAME">doc/webserver/*/*.html</tt>) so that those without the ability
116 to build them locally, have access to them if needed. This is especially
117 important just prior to a new release! Please do this <span class=
118 "emphasis"><i class="EMPHASIS">after</i></span> the <tt class=
119 "LITERAL">$VERSION</tt> and other release specific data in <tt class=
120 "FILENAME">configure.in</tt> has been updated (this is done just prior to
124 <h2 class="SECT2"><a name="SGML" id="SGML">3.1. Quickstart to Docbook
127 <p>If you are not familiar with SGML, it is a markup language similar
128 to HTML. Actually, not a mark up language per se, but a language used
129 to define markup languages. In fact, HTML is an SGML application. Both
130 will use <span class="QUOTE">"tags"</span> to format text and other
131 content. SGML tags can be much more varied, and flexible, but do much
132 of the same kinds of things. The tags, or <span class=
133 "QUOTE">"elements"</span>, are definable in SGML. There is no set
134 <span class="QUOTE">"standards"</span>. Since we are using <span class=
135 "APPLICATION">Docbook</span>, our tags are those that are defined by
136 <span class="APPLICATION">Docbook</span>. Much of how the finish
137 document is rendered is determined by the <span class=
138 "QUOTE">"stylesheets"</span>. The stylesheets determine how each tag
139 gets translated to HTML, or other formats.</p>
141 <p>Tags in Docbook SGML need to be always <span class=
142 "QUOTE">"closed"</span>. If not, you will likely generate errors.
143 Example: <tt class="LITERAL"><title>My Title</title></tt>.
144 They are also case-insensitive, but we strongly suggest using all lower
145 case. This keeps compatibility with [Docbook] <span class=
146 "APPLICATION">XML</span>.</p>
148 <p>Our documents use <span class="QUOTE">"sections"</span> for the most
149 part. Sections will be processed into HTML headers (e.g. <tt class=
150 "LITERAL">h1</tt> for <tt class="LITERAL">sect1</tt>). The <span class=
151 "APPLICATION">Docbook</span> stylesheets will use these to also
152 generate the Table of Contents for each doc. Our TOC's are set to a
153 depth of three. Meaning <tt class="LITERAL">sect1</tt>, <tt class=
154 "LITERAL">sect2</tt>, and <tt class="LITERAL">sect3</tt> will have TOC
155 entries, but <tt class="LITERAL">sect4</tt> will not. Each section
156 requires a <tt class="LITERAL"><title></tt> element, and at least
157 one <tt class="LITERAL"><para></tt>. There is a limit of five
158 section levels in Docbook, but generally three should be sufficient for
161 <p>Some common elements that you likely will use:</p>
166 <td><span class="emphasis"><i class=
167 "EMPHASIS"><para></para></i></span>, paragraph
168 delimiter. Most text needs to be within paragraph elements (there
169 are some exceptions).</td>
173 <td><span class="emphasis"><i class=
174 "EMPHASIS"><emphasis></emphasis></i></span>, the
175 stylesheets make this italics.</td>
179 <td><span class="emphasis"><i class=
180 "EMPHASIS"><filename></filename></i></span>, files
181 and directories.</td>
185 <td><span class="emphasis"><i class=
186 "EMPHASIS"><command></command></i></span>, command
191 <td><span class="emphasis"><i class=
192 "EMPHASIS"><literallayout></literallayout></i></span>,
193 like <tt class="LITERAL"><pre></tt>, more or less.</td>
197 <td><span class="emphasis"><i class=
198 "EMPHASIS"><itemizedlist></itemizedlist></i></span>,
199 list with bullets.</td>
203 <td><span class="emphasis"><i class=
204 "EMPHASIS"><listitem></listitem></i></span>, member
209 <td><span class="emphasis"><i class=
210 "EMPHASIS"><screen></screen></i></span>, screen
211 output, implies <tt class=
212 "LITERAL"><literallayout></tt>.</td>
216 <td><span class="emphasis"><i class="EMPHASIS"><ulink
217 url="example.com"></ulink></i></span>, like HTML
218 <tt class="LITERAL"><a></tt> tag.</td>
222 <td><span class="emphasis"><i class=
223 "EMPHASIS"><quote></quote></i></span>, for, doh,
229 <p>Look at any of the existing docs for examples of all these and
232 <p>You might also find <span class="QUOTE">"<a href=
233 "http://opensource.bureau-cornavin.com/crash-course/index.html" target=
234 "_top">Writing Documentation Using DocBook - A Crash Course</a>"</span>
239 <h2 class="SECT2"><a name="DOCSTYLE" id="DOCSTYLE">3.2. <span class=
240 "APPLICATION">Privoxy</span> Documentation Style</a></h2>
242 <p>It will be easier if everyone follows a similar writing style. This
243 just makes it easier to read what someone else has written if it is all
244 done in a similar fashion.</p>
250 <p>All tags should be lower case.</p>
254 <p>Tags delimiting a <span class="emphasis"><i class=
255 "EMPHASIS">block</i></span> of text (even small blocks) should be
256 on their own line. Like:</p>
258 <p class="LITERALLAYOUT"> <para><br>
259 Some text goes here.<br>
260 </para><br>
261 </p>Tags marking
262 individual words, or few words, should be in-line:
264 <p class="LITERALLAYOUT">
265 Just to <emphasis>emphasize</emphasis>, some text goes here.<br>
267 </p>
271 <p>Tags should be nested and step indented for block text like:
272 (except in-line tags)</p>
274 <p class="LITERALLAYOUT"> <para><br>
275 <itemizedlist><br>
276 <para><br>
277 <listitem><br>
278 Some text goes here in our list example.<br>
280 </listitem><br>
281 </para><br>
282 </itemizedlist><br>
283 </para><br>
284 </p>This makes it easier
285 to find the text amongst the tags ;-)
289 <p>Use white space to separate logical divisions within a document,
290 like between sections. Running everything together consistently
291 makes it harder to read and work on.</p>
295 <p>Do not hesitate to make comments. Comments can either use the
296 <comment> element, or the <!-- --> style comment
297 familiar from HTML. (Note in Docbook v4.x <comment> is
298 replaced by <remark>.)</p>
302 <p>We have an international audience. Refrain from slang, or
303 English idiosyncrasies (too many to list :). Humor also does not
304 translate well sometimes.</p>
308 <p>Try to keep overall line lengths in source files to 80
309 characters or less for obvious reasons. This is not always
310 possible, with lengthy URLs for instance.</p>
314 <p>Our documents are available in differing formats. Right now,
315 they are just plain text, HTML, and PDF, but others are always a
316 future possibility. Be careful with URLs (<ulink>), and avoid
319 <p>My favorite site is <ulink
320 url="http://example.com">here</ulink>.</p>
322 <p>This will render as <span class="QUOTE">"My favorite site is
323 here"</span>, which is not real helpful in a text doc. Better like
326 <p>My favorite site is <ulink
327 url="http://example.com">example.com</ulink>.</p>
331 <p>All documents should be spell checked occasionally. <span class=
332 "APPLICATION">aspell</span> can check SGML with the <tt class=
333 "LITERAL">-H</tt> option. (<span class="APPLICATION">ispell</span>
340 <h2 class="SECT2"><a name="AEN217" id="AEN217">3.3. Privoxy Custom
343 <p><span class="APPLICATION">Privoxy</span> documentation is using a
344 number of customized <span class="QUOTE">"entities"</span> to
345 facilitate documentation maintenance.</p>
347 <p>We are using a set of <span class="QUOTE">"boilerplate"</span> files
348 with generic text, that is used by multiple docs. This way we can write
349 something once, and use it repeatedly without having to re-write the
350 same content over and over again. If editing such a file, keep in mind
351 that it should be <span class="emphasis"><i class=
352 "EMPHASIS">generic</i></span>. That is the purpose; so it can be used
353 in varying contexts without additional modifications.</p>
355 <p>We are also using what <span class="APPLICATION">Docbook</span>
356 calls <span class="QUOTE">"internal entities"</span>. These are like
357 variables in programming. Well, sort of. For instance, we have the
358 <tt class="LITERAL">p-version</tt> entity that contains the current
359 <span class="APPLICATION">Privoxy</span> version string. You are
360 strongly encouraged to use these where possible. Some of these
361 obviously require re-setting with each release (done by the Makefile).
362 A sampling of custom entities are listed below. See any of the main
363 docs for examples.</p>
367 <p>Re- <span class="QUOTE">"boilerplate"</span> text entities are
370 <p><tt class="LITERAL"><!entity supported SYSTEM
371 "supported.sgml"></tt></p>
373 <p>In this example, the contents of the file, <tt class=
374 "FILENAME">supported.sgml</tt> is available for inclusion anywhere
375 in the doc. To make this happen, just reference the now defined
376 entity: <tt class="LITERAL">&supported;</tt> (starts with an
377 ampersand and ends with a semi-colon), and the contents will be
378 dumped into the finished doc at that point.</p>
382 <p>Commonly used <span class="QUOTE">"internal
383 entities"</span>:</p>
388 <td><span class="emphasis"><i class=
389 "EMPHASIS">p-version</i></span>: the <span class=
390 "APPLICATION">Privoxy</span> version string, e.g.
391 <span class="QUOTE">"3.0.19"</span>.</td>
395 <td><span class="emphasis"><i class=
396 "EMPHASIS">p-status</i></span>: the project status, either
397 <span class="QUOTE">"alpha"</span>, <span class=
398 "QUOTE">"beta"</span>, or <span class=
399 "QUOTE">"stable"</span>.</td>
403 <td><span class="emphasis"><i class=
404 "EMPHASIS">p-not-stable</i></span>: use to conditionally
405 include text in <span class="QUOTE">"not stable"</span>
406 releases (e.g. <span class="QUOTE">"beta"</span>).</td>
410 <td><span class="emphasis"><i class=
411 "EMPHASIS">p-stable</i></span>: just the opposite.</td>
415 <td><span class="emphasis"><i class=
416 "EMPHASIS">p-text</i></span>: this doc is only generated as
424 <p>There are others in various places that are defined for a specific
425 purpose. Read the source!</p>
429 <div class="NAVFOOTER">
430 <hr align="left" width="100%">
432 <table summary="Footer navigation table" width="100%" border="0"
433 cellpadding="0" cellspacing="0">
435 <td width="33%" align="left" valign="top"><a href="cvs.html"
436 accesskey="P">Prev</a></td>
438 <td width="34%" align="center" valign="top"><a href="index.html"
439 accesskey="H">Home</a></td>
441 <td width="33%" align="right" valign="top"><a href="coding.html"
442 accesskey="N">Next</a></td>
446 <td width="33%" align="left" valign="top">The CVS Repository</td>
448 <td width="34%" align="center" valign="top"> </td>
450 <td width="33%" align="right" valign="top">Coding Guidelines</td>