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