doc/webserver/developer-manual/documentation.html

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