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