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.26"</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