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