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 </head>
  15
  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">Privoxy Developer Manual</th>
  23       </tr>
  24
  25       <tr>
  26         <td width="10%" align="left" valign="bottom"><a href="cvs.html"
  27         accesskey="P">Prev</a></td>
  28
  29         <td width="80%" align="center" valign="bottom"></td>
  30
  31         <td width="10%" align="right" valign="bottom"><a href="coding.html"
  32         accesskey="N">Next</a></td>
  33       </tr>
  34     </table>
  35     <hr align="left" width="100%">
  36   </div>
  37
  38   <div class="SECT1">
  39     <h1 class="SECT1"><a name="DOCUMENTATION" id="DOCUMENTATION">3.
  40     Documentation Guidelines</a></h1>
  41
  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
  63     documentation.</p>
  64
  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>
  75
  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>
  78
  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>
  84
  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>
  92
  93     <p>Documentation writers should please make sure documents build
  94     successfully before committing to CVS, if possible.</p>
  95
  96     <p>How do you update the webserver (i.e. the pages on privoxy.org)?</p>
  97
  98     <ol type="1">
  99       <li>
 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>
 104       </li>
 105
 106       <li>
 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
 110         via scp.</p>
 111       </li>
 112     </ol>
 113
 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
 121     a new release).</p>
 122
 123     <div class="SECT2">
 124       <h2 class="SECT2"><a name="SGML" id="SGML">3.1. Quickstart to Docbook
 125       and SGML</a></h2>
 126
 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>
 140
 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">&lt;title&gt;My Title&lt;/title&gt;</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>
 147
 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">&lt;title&gt;</tt> element, and at least
 157       one <tt class="LITERAL">&lt;para&gt;</tt>. There is a limit of five
 158       section levels in Docbook, but generally three should be sufficient for
 159       our purposes.</p>
 160
 161       <p>Some common elements that you likely will use:</p>
 162
 163       <table border="0">
 164         <tbody>
 165           <tr>
 166             <td><span class="emphasis"><i class=
 167             "EMPHASIS">&lt;para&gt;&lt;/para&gt;</i></span>, paragraph
 168             delimiter. Most text needs to be within paragraph elements (there
 169             are some exceptions).</td>
 170           </tr>
 171
 172           <tr>
 173             <td><span class="emphasis"><i class=
 174             "EMPHASIS">&lt;emphasis&gt;&lt;/emphasis&gt;</i></span>, the
 175             stylesheets make this italics.</td>
 176           </tr>
 177
 178           <tr>
 179             <td><span class="emphasis"><i class=
 180             "EMPHASIS">&lt;filename&gt;&lt;/filename&gt;</i></span>, files
 181             and directories.</td>
 182           </tr>
 183
 184           <tr>
 185             <td><span class="emphasis"><i class=
 186             "EMPHASIS">&lt;command&gt;&lt;/command&gt;</i></span>, command
 187             examples.</td>
 188           </tr>
 189
 190           <tr>
 191             <td><span class="emphasis"><i class=
 192             "EMPHASIS">&lt;literallayout&gt;&lt;/literallayout&gt;</i></span>,
 193             like <tt class="LITERAL">&lt;pre&gt;</tt>, more or less.</td>
 194           </tr>
 195
 196           <tr>
 197             <td><span class="emphasis"><i class=
 198             "EMPHASIS">&lt;itemizedlist&gt;&lt;/itemizedlist&gt;</i></span>,
 199             list with bullets.</td>
 200           </tr>
 201
 202           <tr>
 203             <td><span class="emphasis"><i class=
 204             "EMPHASIS">&lt;listitem&gt;&lt;/listitem&gt;</i></span>, member
 205             of the above.</td>
 206           </tr>
 207
 208           <tr>
 209             <td><span class="emphasis"><i class=
 210             "EMPHASIS">&lt;screen&gt;&lt;/screen&gt;</i></span>, screen
 211             output, implies <tt class=
 212             "LITERAL">&lt;literallayout&gt;</tt>.</td>
 213           </tr>
 214
 215           <tr>
 216             <td><span class="emphasis"><i class="EMPHASIS">&lt;ulink
 217             url="example.com"&gt;&lt;/ulink&gt;</i></span>, like HTML
 218             <tt class="LITERAL">&lt;a&gt;</tt> tag.</td>
 219           </tr>
 220
 221           <tr>
 222             <td><span class="emphasis"><i class=
 223             "EMPHASIS">&lt;quote&gt;&lt;/quote&gt;</i></span>, for, doh,
 224             quoting text.</td>
 225           </tr>
 226         </tbody>
 227       </table>
 228
 229       <p>Look at any of the existing docs for examples of all these and
 230       more.</p>
 231
 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>
 235       useful.</p>
 236     </div>
 237
 238     <div class="SECT2">
 239       <h2 class="SECT2"><a name="DOCSTYLE" id="DOCSTYLE">3.2. <span class=
 240       "APPLICATION">Privoxy</span> Documentation Style</a></h2>
 241
 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>
 245
 246       <p>Here it is:</p>
 247
 248       <ul>
 249         <li>
 250           <p>All tags should be lower case.</p>
 251         </li>
 252
 253         <li>
 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>
 257
 258           <p class="LITERALLAYOUT">&nbsp;&lt;para&gt;<br>
 259           &nbsp;&nbsp;Some&nbsp;text&nbsp;goes&nbsp;here.<br>
 260           &nbsp;&lt;/para&gt;<br>
 261           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</p>Tags marking
 262           individual words, or few words, should be in-line:
 263
 264           <p class="LITERALLAYOUT">
 265           &nbsp;&nbsp;Just&nbsp;to&nbsp;&lt;emphasis&gt;emphasize&lt;/emphasis&gt;,&nbsp;some&nbsp;text&nbsp;goes&nbsp;here.<br>
 266
 267           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</p>
 268         </li>
 269
 270         <li>
 271           <p>Tags should be nested and step indented for block text like:
 272           (except in-line tags)</p>
 273
 274           <p class="LITERALLAYOUT">&nbsp;&lt;para&gt;<br>
 275           &nbsp;&nbsp;&lt;itemizedlist&gt;<br>
 276           &nbsp;&nbsp;&nbsp;&lt;para&gt;<br>
 277           &nbsp;&nbsp;&nbsp;&nbsp;&lt;listitem&gt;<br>
 278           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Some&nbsp;text&nbsp;goes&nbsp;here&nbsp;in&nbsp;our&nbsp;list&nbsp;example.<br>
 279
 280           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/listitem&gt;<br>
 281           &nbsp;&nbsp;&nbsp;&lt;/para&gt;<br>
 282           &nbsp;&nbsp;&lt;/itemizedlist&gt;<br>
 283           &nbsp;&lt;/para&gt;<br>
 284           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</p>This makes it easier
 285           to find the text amongst the tags ;-)
 286         </li>
 287
 288         <li>
 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>
 292         </li>
 293
 294         <li>
 295           <p>Do not hesitate to make comments. Comments can either use the
 296           &lt;comment&gt; element, or the &lt;!-- --&gt; style comment
 297           familiar from HTML. (Note in Docbook v4.x &lt;comment&gt; is
 298           replaced by &lt;remark&gt;.)</p>
 299         </li>
 300
 301         <li>
 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>
 305         </li>
 306
 307         <li>
 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>
 311         </li>
 312
 313         <li>
 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 (&lt;ulink&gt;), and avoid
 317           this mistake:</p>
 318
 319           <p>My favorite site is &lt;ulink
 320           url="http://example.com"&gt;here&lt;/ulink&gt;.</p>
 321
 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
 324           this:</p>
 325
 326           <p>My favorite site is &lt;ulink
 327           url="http://example.com"&gt;example.com&lt;/ulink&gt;.</p>
 328         </li>
 329
 330         <li>
 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>
 334           I think too.)</p>
 335         </li>
 336       </ul>
 337     </div>
 338
 339     <div class="SECT2">
 340       <h2 class="SECT2"><a name="AEN217" id="AEN217">3.3. Privoxy Custom
 341       Entities</a></h2>
 342
 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>
 346
 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>
 354
 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>
 364
 365       <ul>
 366         <li>
 367           <p>Re- <span class="QUOTE">"boilerplate"</span> text entities are
 368           defined like:</p>
 369
 370           <p><tt class="LITERAL">&lt;!entity supported SYSTEM
 371           "supported.sgml"&gt;</tt></p>
 372
 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">&amp;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>
 379         </li>
 380
 381         <li>
 382           <p>Commonly used <span class="QUOTE">"internal
 383           entities"</span>:</p>
 384
 385           <table border="0">
 386             <tbody>
 387               <tr>
 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>
 392               </tr>
 393
 394               <tr>
 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>
 400               </tr>
 401
 402               <tr>
 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>
 407               </tr>
 408
 409               <tr>
 410                 <td><span class="emphasis"><i class=
 411                 "EMPHASIS">p-stable</i></span>: just the opposite.</td>
 412               </tr>
 413
 414               <tr>
 415                 <td><span class="emphasis"><i class=
 416                 "EMPHASIS">p-text</i></span>: this doc is only generated as
 417                 text.</td>
 418               </tr>
 419             </tbody>
 420           </table>
 421         </li>
 422       </ul>
 423
 424       <p>There are others in various places that are defined for a specific
 425       purpose. Read the source!</p>
 426     </div>
 427   </div>
 428
 429   <div class="NAVFOOTER">
 430     <hr align="left" width="100%">
 431
 432     <table summary="Footer navigation table" width="100%" border="0"
 433     cellpadding="0" cellspacing="0">
 434       <tr>
 435         <td width="33%" align="left" valign="top"><a href="cvs.html"
 436         accesskey="P">Prev</a></td>
 437
 438         <td width="34%" align="center" valign="top"><a href="index.html"
 439         accesskey="H">Home</a></td>
 440
 441         <td width="33%" align="right" valign="top"><a href="coding.html"
 442         accesskey="N">Next</a></td>
 443       </tr>
 444
 445       <tr>
 446         <td width="33%" align="left" valign="top">The CVS Repository</td>
 447
 448         <td width="34%" align="center" valign="top">&nbsp;</td>
 449
 450         <td width="33%" align="right" valign="top">Coding Guidelines</td>
 451       </tr>
 452     </table>
 453   </div>
 454 </body>
 455 </html>