1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
6 <meta name="generator" content=
7 "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
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">
19 background-color: #EEEEEE;
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}
32 <div class="NAVHEADER">
33 <table summary="Header navigation table" width="100%" border="0"
34 cellpadding="0" cellspacing="0">
36 <th colspan="3" align="center">Privoxy Developer Manual</th>
40 <td width="10%" align="left" valign="bottom"><a href="cvs.html"
41 accesskey="P">Prev</a></td>
43 <td width="80%" align="center" valign="bottom"></td>
45 <td width="10%" align="right" valign="bottom"><a href="coding.html"
46 accesskey="N">Next</a></td>
49 <hr class="c1" width="100%">
53 <h1 class="SECT1"><a name="DOCUMENTATION" id="DOCUMENTATION">3.
54 Documentation Guidelines</a></h1>
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>
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>
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>
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>
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>
106 <p>Documentation writers should please make sure documents build
107 successfully before committing to CVS, if possible.</p>
109 <p>How do you update the webserver (i.e. the pages on privoxy.org)?</p>
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>
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
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>
136 <h2 class="SECT2"><a name="SGML" id="SGML">3.1. Quickstart to Docbook
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>
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"><title>My Title</title></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>
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"><title></tt> element, and at least
169 one <tt class="LITERAL"><para></tt>. There is a limit of five
170 section levels in Docbook, but generally three should be sufficient for
173 <p>Some common elements that you likely will use:</p>
179 "emphasis EMPHASIS c3"><para></para></span>,
180 paragraph delimiter. Most text needs to be within paragraph
181 elements (there are some exceptions).</td>
186 "emphasis EMPHASIS c3"><emphasis></emphasis></span>,
187 the stylesheets make this italics.</td>
192 "emphasis EMPHASIS c3"><filename></filename></span>,
193 files and directories.</td>
198 "emphasis EMPHASIS c3"><command></command></span>,
199 command examples.</td>
204 "emphasis EMPHASIS c3"><literallayout></literallayout></span>,
205 like <tt class="LITERAL"><pre></tt>, more or less.</td>
210 "emphasis EMPHASIS c3"><itemizedlist></itemizedlist></span>,
211 list with bullets.</td>
216 "emphasis EMPHASIS c3"><listitem></listitem></span>,
217 member of the above.</td>
222 "emphasis EMPHASIS c3"><screen></screen></span>,
223 screen output, implies <tt class=
224 "LITERAL"><literallayout></tt>.</td>
228 <td><span class="emphasis EMPHASIS c3"><ulink
229 url="example.com"></ulink></span>, like HTML <tt class=
230 "LITERAL"><a></tt> tag.</td>
235 "emphasis EMPHASIS c3"><quote></quote></span>, for,
236 doh, quoting text.</td>
241 <p>Look at any of the existing docs for examples of all these and
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>
251 <h2 class="SECT2"><a name="DOCSTYLE" id="DOCSTYLE">3.2. <span class=
252 "APPLICATION">Privoxy</span> Documentation Style</a></h2>
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>
262 <p>All tags should be lower case.</p>
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>
270 <p class="LITERALLAYOUT"> <para><br>
271 Some text goes here.<br>
272 </para><br>
273 </p>Tags marking
274 individual words, or few words, should be in-line:
276 <p class="LITERALLAYOUT">
277 Just to <emphasis>emphasize</emphasis>, some text goes here.<br>
279 </p>
283 <p>Tags should be nested and step indented for block text like:
284 (except in-line tags)</p>
286 <p class="LITERALLAYOUT"> <para><br>
287 <itemizedlist><br>
288 <para><br>
289 <listitem><br>
290 Some text goes here in our list example.<br>
292 </listitem><br>
293 </para><br>
294 </itemizedlist><br>
295 </para><br>
296 </p>This makes it easier
297 to find the text amongst the tags ;-)
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>
307 <p>Do not hesitate to make comments. Comments can either use the
308 <comment> element, or the <!-- --> style comment
309 familiar from HTML. (Note in Docbook v4.x <comment> is
310 replaced by <remark>.)</p>
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>
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>
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 (<ulink>), and avoid
331 <p>My favorite site is <ulink
332 url="http://example.com">here</ulink>.</p>
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
338 <p>My favorite site is <ulink
339 url="http://example.com">example.com</ulink>.</p>
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>
352 <h2 class="SECT2"><a name="AEN217" id="AEN217">3.3. Privoxy Custom
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>
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>
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>
379 <p>Re- <span class="QUOTE">"boilerplate"</span> text entities are
382 <p><tt class="LITERAL"><!entity supported SYSTEM
383 "supported.sgml"></tt></p>
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">&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>
394 <p>Commonly used <span class="QUOTE">"internal
395 entities"</span>:</p>
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.18"</span>.</td>
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>
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>
420 <td><span class="emphasis EMPHASIS c3">p-stable</span>: just
425 <td><span class="emphasis EMPHASIS c3">p-text</span>: this
426 doc is only generated as text.</td>
433 <p>There are others in various places that are defined for a specific
434 purpose. Read the source!</p>
438 <div class="NAVFOOTER">
439 <hr class="c1" width="100%">
441 <table summary="Footer navigation table" width="100%" border="0"
442 cellpadding="0" cellspacing="0">
444 <td width="33%" align="left" valign="top"><a href="cvs.html"
445 accesskey="P">Prev</a></td>
447 <td width="34%" align="center" valign="top"><a href="index.html"
448 accesskey="H">Home</a></td>
450 <td width="33%" align="right" valign="top"><a href="coding.html"
451 accesskey="N">Next</a></td>
455 <td width="33%" align="left" valign="top">The CVS Repository</td>
457 <td width="34%" align="center" valign="top"> </td>
459 <td width="33%" align="right" valign="top">Coding Guidelines</td>