65d95584faa6d0329ac2a13127ad0357574ef7f4
[privoxy.git] / doc / webserver / developer-manual / documentation.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
2 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
3 <html>
4   <head>
5     <title>
6       Documentation Guidelines
7     </title>
8     <meta name="GENERATOR" content=
9     "Modular DocBook HTML Stylesheet Version 1.79">
10     <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
11     <link rel="PREVIOUS" title="The CVS Repository" href="cvs.html">
12     <link rel="NEXT" title="Coding Guidelines" href="coding.html">
13     <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
14     <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
15   </head>
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">
21         <tr>
22           <th colspan="3" align="center">
23             Privoxy Developer Manual
24           </th>
25         </tr>
26         <tr>
27           <td width="10%" align="left" valign="bottom">
28             <a href="cvs.html" accesskey="P">Prev</a>
29           </td>
30           <td width="80%" align="center" valign="bottom">
31           </td>
32           <td width="10%" align="right" valign="bottom">
33             <a href="coding.html" accesskey="N">Next</a>
34           </td>
35         </tr>
36       </table>
37       <hr align="LEFT" width="100%">
38     </div>
39     <div class="SECT1">
40       <h1 class="SECT1">
41         <a name="DOCUMENTATION">3. Documentation Guidelines</a>
42       </h1>
43       <p>
44         All formal documents are maintained in Docbook SGML and located in
45         the <samp class="COMPUTEROUTPUT">doc/source/*</samp> directory. You
46         will need <a href="http://www.docbook.org" target="_top">Docbook</a>,
47         the Docbook DTD's and the Docbook modular stylesheets (or comparable
48         alternatives), and either <span class="APPLICATION">jade</span> or
49         <span class="APPLICATION">openjade</span> (recommended) installed in
50         order to build docs from source. Currently there is <a href=
51         "../user-manual/index.html" target="_top"><i class=
52         "CITETITLE">user-manual</i></a>, <a href="../faq/index.html" target=
53         "_top"><i class="CITETITLE">FAQ</i></a>, and, of course this, the <i
54         class="CITETITLE">developer-manual</i> in this format. The <i class=
55         "CITETITLE">README</i>, <i class="CITETITLE">AUTHORS</i>, <i class=
56         "CITETITLE">INSTALL</i>, <i class="CITETITLE">privoxy.1</i> (man
57         page), and <i class="CITETITLE">config</i> files are also now
58         maintained as Docbook SGML. These files, when built, in the top-level
59         source directory are generated files! Also, the <span class=
60         "APPLICATION">Privoxy</span> <tt class="FILENAME">index.html</tt>
61         (and a variation on this file, <tt class=
62         "FILENAME">privoxy-index.html</tt>, meant for inclusion with doc
63         packages), are maintained as SGML as well. <span class="emphasis"><i
64         class="EMPHASIS">DO NOT edit these directly</i></span>. Edit the SGML
65         source, or contact someone involved in the documentation.
66       </p>
67       <p>
68         <tt class="FILENAME">config</tt> requires some special handling. The
69         reason it is maintained this way is so that the extensive comments in
70         the file mirror those in <i class="CITETITLE">user-manual</i>. But
71         the conversion process requires going from SGML to HTML to text to
72         special formatting required for the embedded comments. Some of this
73         does not survive so well. Especially some of the examples that are
74         longer than 80 characters. The build process for this file outputs to
75         <tt class="FILENAME">config.new</tt>, which should be reviewed for
76         errors and mis-formatting. Once satisfied that it is correct, then it
77         should be hand copied to <tt class="FILENAME">config</tt>.
78       </p>
79       <p>
80         Other, less formal documents (e.g. <tt class="FILENAME">LICENSE</tt>)
81         are maintained as plain text files in the top-level source directory.
82       </p>
83       <p>
84         Packagers are encouraged to include this documentation. For those
85         without the ability to build the docs locally, text versions of each
86         are kept in CVS. HTML versions are also being kept in CVS under <tt
87         class="FILENAME">doc/webserver/*</tt>.
88       </p>
89       <p>
90         Formal documents are built with the Makefile targets of <samp class=
91         "COMPUTEROUTPUT">make dok</samp>. The build process uses the document
92         SGML sources in <samp class="COMPUTEROUTPUT">doc/source/*/*</samp> to
93         update all text files in <samp class=
94         "COMPUTEROUTPUT">doc/text/</samp> and to update all HTML documents in
95         <samp class="COMPUTEROUTPUT">doc/webserver/</samp>.
96       </p>
97       <p>
98         Documentation writers should please make sure documents build
99         successfully before committing to CVS, if possible.
100       </p>
101       <p>
102         How do you update the webserver (i.e. the pages on privoxy.org)?
103       </p>
104       <ol type="1">
105         <li>
106           <p>
107             First, build the docs by running <samp class=
108             "COMPUTEROUTPUT">make dok</samp>.
109           </p>
110         </li>
111         <li>
112           <p>
113             Run <samp class="COMPUTEROUTPUT">make webserver</samp> which
114             copies all files from <samp class=
115             "COMPUTEROUTPUT">doc/webserver</samp> to the sourceforge
116             webserver via scp.
117           </p>
118         </li>
119       </ol>
120
121       <p>
122         Finished docs should be occasionally submitted to CVS (<tt class=
123         "FILENAME">doc/webserver/*/*.html</tt>) so that those without the
124         ability to build them locally, have access to them if needed. This is
125         especially important just prior to a new release! Please do this
126         <span class="emphasis"><i class="EMPHASIS">after</i></span> the <tt
127         class="LITERAL">$VERSION</tt> and other release specific data in <tt
128         class="FILENAME">configure.in</tt> has been updated (this is done
129         just prior to a new release).
130       </p>
131       <div class="SECT2">
132         <h2 class="SECT2">
133           <a name="SGML">3.1. Quickstart to Docbook and SGML</a>
134         </h2>
135         <p>
136           If you are not familiar with SGML, it is a markup language similar
137           to HTML. Actually, not a mark up language per se, but a language
138           used to define markup languages. In fact, HTML is an SGML
139           application. Both will use <span class="QUOTE">"tags"</span> to
140           format text and other content. SGML tags can be much more varied,
141           and flexible, but do much of the same kinds of things. The tags, or
142           <span class="QUOTE">"elements"</span>, are definable in SGML. There
143           is no set <span class="QUOTE">"standards"</span>. Since we are
144           using <span class="APPLICATION">Docbook</span>, our tags are those
145           that are defined by <span class="APPLICATION">Docbook</span>. Much
146           of how the finish document is rendered is determined by the <span
147           class="QUOTE">"stylesheets"</span>. The stylesheets determine how
148           each tag gets translated to HTML, or other formats.
149         </p>
150         <p>
151           Tags in Docbook SGML need to be always <span class=
152           "QUOTE">"closed"</span>. If not, you will likely generate errors.
153           Example: <tt class="LITERAL">&lt;title&gt;My
154           Title&lt;/title&gt;</tt>. They are also case-insensitive, but we
155           strongly suggest using all lower case. This keeps compatibility
156           with [Docbook] <span class="APPLICATION">XML</span>.
157         </p>
158         <p>
159           Our documents use <span class="QUOTE">"sections"</span> for the
160           most part. Sections will be processed into HTML headers (e.g. <tt
161           class="LITERAL">h1</tt> for <tt class="LITERAL">sect1</tt>). The
162           <span class="APPLICATION">Docbook</span> stylesheets will use these
163           to also generate the Table of Contents for each doc. Our TOC's are
164           set to a depth of three. Meaning <tt class="LITERAL">sect1</tt>,
165           <tt class="LITERAL">sect2</tt>, and <tt class="LITERAL">sect3</tt>
166           will have TOC entries, but <tt class="LITERAL">sect4</tt> will not.
167           Each section requires a <tt class="LITERAL">&lt;title&gt;</tt>
168           element, and at least one <tt class="LITERAL">&lt;para&gt;</tt>.
169           There is a limit of five section levels in Docbook, but generally
170           three should be sufficient for our purposes.
171         </p>
172         <p>
173           Some common elements that you likely will use:
174         </p>
175         <p>
176         </p>
177         <table border="0">
178           <tbody>
179             <tr>
180               <td>
181                 <span class="emphasis"><i class=
182                 "EMPHASIS">&lt;para&gt;&lt;/para&gt;</i></span>, paragraph
183                 delimiter. Most text needs to be within paragraph elements
184                 (there are some exceptions).
185               </td>
186             </tr>
187             <tr>
188               <td>
189                 <span class="emphasis"><i class=
190                 "EMPHASIS">&lt;emphasis&gt;&lt;/emphasis&gt;</i></span>, the
191                 stylesheets make this italics.
192               </td>
193             </tr>
194             <tr>
195               <td>
196                 <span class="emphasis"><i class=
197                 "EMPHASIS">&lt;filename&gt;&lt;/filename&gt;</i></span>,
198                 files and directories.
199               </td>
200             </tr>
201             <tr>
202               <td>
203                 <span class="emphasis"><i class=
204                 "EMPHASIS">&lt;command&gt;&lt;/command&gt;</i></span>,
205                 command examples.
206               </td>
207             </tr>
208             <tr>
209               <td>
210                 <span class="emphasis"><i class=
211                 "EMPHASIS">&lt;literallayout&gt;&lt;/literallayout&gt;</i></span>,
212                 like <tt class="LITERAL">&lt;pre&gt;</tt>, more or less.
213               </td>
214             </tr>
215             <tr>
216               <td>
217                 <span class="emphasis"><i class=
218                 "EMPHASIS">&lt;itemizedlist&gt;&lt;/itemizedlist&gt;</i></span>,
219                 list with bullets.
220               </td>
221             </tr>
222             <tr>
223               <td>
224                 <span class="emphasis"><i class=
225                 "EMPHASIS">&lt;listitem&gt;&lt;/listitem&gt;</i></span>,
226                 member of the above.
227               </td>
228             </tr>
229             <tr>
230               <td>
231                 <span class="emphasis"><i class=
232                 "EMPHASIS">&lt;screen&gt;&lt;/screen&gt;</i></span>, screen
233                 output, implies <tt class=
234                 "LITERAL">&lt;literallayout&gt;</tt>.
235               </td>
236             </tr>
237             <tr>
238               <td>
239                 <span class="emphasis"><i class="EMPHASIS">&lt;ulink
240                 url="example.com"&gt;&lt;/ulink&gt;</i></span>, like HTML <tt
241                 class="LITERAL">&lt;a&gt;</tt> tag.
242               </td>
243             </tr>
244             <tr>
245               <td>
246                 <span class="emphasis"><i class=
247                 "EMPHASIS">&lt;quote&gt;&lt;/quote&gt;</i></span>, for, doh,
248                 quoting text.
249               </td>
250             </tr>
251           </tbody>
252         </table>
253
254         <p>
255           Look at any of the existing docs for examples of all these and
256           more.
257         </p>
258         <p>
259           You might also find <span class="QUOTE">"<a href=
260           "http://opensource.bureau-cornavin.com/crash-course/index.html"
261           target="_top">Writing Documentation Using DocBook - A Crash
262           Course</a>"</span> useful.
263         </p>
264       </div>
265       <div class="SECT2">
266         <h2 class="SECT2">
267           <a name="DOCSTYLE">3.2. <span class="APPLICATION">Privoxy</span>
268           Documentation Style</a>
269         </h2>
270         <p>
271           It will be easier if everyone follows a similar writing style. This
272           just makes it easier to read what someone else has written if it is
273           all done in a similar fashion.
274         </p>
275         <p>
276           Here it is:
277         </p>
278         <p>
279         </p>
280         <ul>
281           <li>
282             <p>
283               All tags should be lower case.
284             </p>
285           </li>
286           <li>
287             <p>
288               Tags delimiting a <span class="emphasis"><i class=
289               "EMPHASIS">block</i></span> of text (even small blocks) should
290               be on their own line. Like:
291             </p>
292             <p class="LITERALLAYOUT">
293               &nbsp;&lt;para&gt;<br>
294                &nbsp;&nbsp;Some&nbsp;text&nbsp;goes&nbsp;here.<br>
295                &nbsp;&lt;/para&gt;<br>
296                &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
297             </p>
298             Tags marking individual words, or few words, should be in-line:
299             <p class="LITERALLAYOUT">
300               &nbsp;&nbsp;Just&nbsp;to&nbsp;&lt;emphasis&gt;emphasize&lt;/emphasis&gt;,&nbsp;some&nbsp;text&nbsp;goes&nbsp;here.<br>
301
302                &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
303             </p>
304           </li>
305           <li>
306             <p>
307               Tags should be nested and step indented for block text like:
308               (except in-line tags)
309             </p>
310             <p class="LITERALLAYOUT">
311               &nbsp;&lt;para&gt;<br>
312                &nbsp;&nbsp;&lt;itemizedlist&gt;<br>
313                &nbsp;&nbsp;&nbsp;&lt;para&gt;<br>
314                &nbsp;&nbsp;&nbsp;&nbsp;&lt;listitem&gt;<br>
315                &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Some&nbsp;text&nbsp;goes&nbsp;here&nbsp;in&nbsp;our&nbsp;list&nbsp;example.<br>
316
317                &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/listitem&gt;<br>
318                &nbsp;&nbsp;&nbsp;&lt;/para&gt;<br>
319                &nbsp;&nbsp;&lt;/itemizedlist&gt;<br>
320                &nbsp;&lt;/para&gt;<br>
321                &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
322             </p>
323             This makes it easier to find the text amongst the tags ;-)<br>
324           </li>
325           <li>
326             <p>
327               Use white space to separate logical divisions within a
328               document, like between sections. Running everything together
329               consistently makes it harder to read and work on.
330             </p>
331           </li>
332           <li>
333             <p>
334               Do not hesitate to make comments. Comments can either use the
335               &lt;comment&gt; element, or the &lt;!-- --&gt; style comment
336               familiar from HTML. (Note in Docbook v4.x &lt;comment&gt; is
337               replaced by &lt;remark&gt;.)
338             </p>
339           </li>
340           <li>
341             <p>
342               We have an international audience. Refrain from slang, or
343               English idiosyncrasies (too many to list :). Humor also does
344               not translate well sometimes.
345             </p>
346           </li>
347           <li>
348             <p>
349               Try to keep overall line lengths in source files to 80
350               characters or less for obvious reasons. This is not always
351               possible, with lengthy URLs for instance.
352             </p>
353           </li>
354           <li>
355             <p>
356               Our documents are available in differing formats. Right now,
357               they are just plain text and/or HTML, but others are always a
358               future possibility. Be careful with URLs (&lt;ulink&gt;), and
359               avoid this mistake:
360             </p>
361             <p>
362               My favorite site is &lt;ulink
363               url="http://example.com"&gt;here&lt;/ulink&gt;.
364             </p>
365             <p>
366               This will render as <span class="QUOTE">"My favorite site is
367               here"</span>, which is not real helpful in a text doc. Better
368               like this:
369             </p>
370             <p>
371               My favorite site is &lt;ulink
372               url="http://example.com"&gt;example.com&lt;/ulink&gt;.
373             </p>
374           </li>
375           <li>
376             <p>
377               All documents should be spell checked occasionally. <span
378               class="APPLICATION">aspell</span> can check SGML with the <tt
379               class="LITERAL">-H</tt> option. (<span class=
380               "APPLICATION">ispell</span> I think too.)
381             </p>
382           </li>
383         </ul>
384       </div>
385       <div class="SECT2">
386         <h2 class="SECT2">
387           <a name="AEN207">3.3. Privoxy Custom Entities</a>
388         </h2>
389         <p>
390           <span class="APPLICATION">Privoxy</span> documentation is using a
391           number of customized <span class="QUOTE">"entities"</span> to
392           facilitate documentation maintenance.
393         </p>
394         <p>
395           We are using a set of <span class="QUOTE">"boilerplate"</span>
396           files with generic text, that is used by multiple docs. This way we
397           can write something once, and use it repeatedly without having to
398           re-write the same content over and over again. If editing such a
399           file, keep in mind that it should be <span class="emphasis"><i
400           class="EMPHASIS">generic</i></span>. That is the purpose; so it can
401           be used in varying contexts without additional modifications.
402         </p>
403         <p>
404           We are also using what <span class="APPLICATION">Docbook</span>
405           calls <span class="QUOTE">"internal entities"</span>. These are
406           like variables in programming. Well, sort of. For instance, we have
407           the <tt class="LITERAL">p-version</tt> entity that contains the
408           current <span class="APPLICATION">Privoxy</span> version string.
409           You are strongly encouraged to use these where possible. Some of
410           these obviously require re-setting with each release (done by the
411           Makefile). A sampling of custom entities are listed below. See any
412           of the main docs for examples.
413         </p>
414         <p>
415         </p>
416         <ul>
417           <li>
418             <p>
419               Re- <span class="QUOTE">"boilerplate"</span> text entities are
420               defined like:
421             </p>
422             <p>
423               <tt class="LITERAL">&lt;!entity supported SYSTEM
424               "supported.sgml"&gt;</tt>
425             </p>
426             <p>
427               In this example, the contents of the file, <tt class=
428               "FILENAME">supported.sgml</tt> is available for inclusion
429               anywhere in the doc. To make this happen, just reference the
430               now defined entity: <tt class="LITERAL">&amp;supported;</tt>
431               (starts with an ampersand and ends with a semi-colon), and the
432               contents will be dumped into the finished doc at that point.
433             </p>
434           </li>
435           <li>
436             <p>
437               Commonly used <span class="QUOTE">"internal entities"</span>:
438             </p>
439             <table border="0">
440               <tbody>
441                 <tr>
442                   <td>
443                     <span class="emphasis"><i class=
444                     "EMPHASIS">p-version</i></span>: the <span class=
445                     "APPLICATION">Privoxy</span> version string, e.g. <span
446                     class="QUOTE">"3.0.25"</span>.
447                   </td>
448                 </tr>
449                 <tr>
450                   <td>
451                     <span class="emphasis"><i class=
452                     "EMPHASIS">p-status</i></span>: the project status,
453                     either <span class="QUOTE">"alpha"</span>, <span class=
454                     "QUOTE">"beta"</span>, or <span class=
455                     "QUOTE">"stable"</span>.
456                   </td>
457                 </tr>
458                 <tr>
459                   <td>
460                     <span class="emphasis"><i class=
461                     "EMPHASIS">p-not-stable</i></span>: use to conditionally
462                     include text in <span class="QUOTE">"not stable"</span>
463                     releases (e.g. <span class="QUOTE">"beta"</span>).
464                   </td>
465                 </tr>
466                 <tr>
467                   <td>
468                     <span class="emphasis"><i class=
469                     "EMPHASIS">p-stable</i></span>: just the opposite.
470                   </td>
471                 </tr>
472                 <tr>
473                   <td>
474                     <span class="emphasis"><i class=
475                     "EMPHASIS">p-text</i></span>: this doc is only generated
476                     as text.
477                   </td>
478                 </tr>
479               </tbody>
480             </table>
481           </li>
482         </ul>
483
484         <p>
485           There are others in various places that are defined for a specific
486           purpose. Read the source!
487         </p>
488       </div>
489     </div>
490     <div class="NAVFOOTER">
491       <hr align="LEFT" width="100%">
492       <table summary="Footer navigation table" width="100%" border="0"
493       cellpadding="0" cellspacing="0">
494         <tr>
495           <td width="33%" align="left" valign="top">
496             <a href="cvs.html" accesskey="P">Prev</a>
497           </td>
498           <td width="34%" align="center" valign="top">
499             <a href="index.html" accesskey="H">Home</a>
500           </td>
501           <td width="33%" align="right" valign="top">
502             <a href="coding.html" accesskey="N">Next</a>
503           </td>
504         </tr>
505         <tr>
506           <td width="33%" align="left" valign="top">
507             The CVS Repository
508           </td>
509           <td width="34%" align="center" valign="top">
510             &nbsp;
511           </td>
512           <td width="33%" align="right" valign="top">
513             Coding Guidelines
514           </td>
515         </tr>
516       </table>
517     </div>
518   </body>
519 </html>
520