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