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