1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
6 <title>Documentation Guidelines</title>
7 <meta name="GENERATOR" content=
8 "Modular DocBook HTML Stylesheet Version 1.79">
9 <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
10 <link rel="PREVIOUS" title="The CVS Repository" href="cvs.html">
11 <link rel="NEXT" title="Coding Guidelines" href="coding.html">
12 <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
13 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
14 <style type="text/css">
16 background-color: #EEEEEE;
19 :link { color: #0000FF }
20 :visited { color: #840084 }
21 :active { color: #0000FF }
22 span.c3 {font-style: italic}
23 a.c2 {font-style: italic}
24 hr.c1 {text-align: left}
29 <div class="NAVHEADER">
30 <table summary="Header navigation table" width="100%" border="0"
31 cellpadding="0" cellspacing="0">
33 <th colspan="3" align="center">Privoxy Developer Manual</th>
37 <td width="10%" align="left" valign="bottom"><a href="cvs.html"
38 accesskey="P">Prev</a></td>
40 <td width="80%" align="center" valign="bottom"></td>
42 <td width="10%" align="right" valign="bottom"><a href="coding.html"
43 accesskey="N">Next</a></td>
46 <hr class="c1" width="100%">
50 <h1 class="SECT1"><a name="DOCUMENTATION" id="DOCUMENTATION">3.
51 Documentation Guidelines</a></h1>
53 <p>All formal documents are maintained in Docbook SGML and located in the
54 <samp class="COMPUTEROUTPUT">doc/source/*</samp> directory. You will need
55 <a href="http://www.docbook.org" target="_top">Docbook</a>, the Docbook
56 DTD's and the Docbook modular stylesheets (or comparable alternatives),
57 and either <span class="APPLICATION">jade</span> or <span class=
58 "APPLICATION">openjade</span> (recommended) installed in order to build
59 docs from source. Currently there is <a class="CITETITLE c2" href=
60 "../user-manual/index.html" target="_top">user-manual</a>, <a class=
61 "CITETITLE c2" href="../faq/index.html" target="_top">FAQ</a>, and, of
62 course this, the <i class="CITETITLE">developer-manual</i> in this
63 format. The <i class="CITETITLE">README</i>, <i class=
64 "CITETITLE">AUTHORS</i>, <i class="CITETITLE">INSTALL</i>, <i class=
65 "CITETITLE">privoxy.1</i> (man page), and <i class="CITETITLE">config</i>
66 files are also now maintained as Docbook SGML. These files, when built,
67 in the top-level source directory are generated files! Also, the
68 <span class="APPLICATION">Privoxy</span> <tt class=
69 "FILENAME">index.html</tt> (and a variation on this file, <tt class=
70 "FILENAME">privoxy-index.html</tt>, meant for inclusion with doc
71 packages), are maintained as SGML as well. <span class=
72 "emphasis EMPHASIS c3">DO NOT edit these directly</span>. Edit the SGML
73 source, or contact someone involved in the documentation.</p>
75 <p><tt class="FILENAME">config</tt> requires some special handling. The
76 reason it is maintained this way is so that the extensive comments in the
77 file mirror those in <i class="CITETITLE">user-manual</i>. But the
78 conversion process requires going from SGML to HTML to text to special
79 formatting required for the embedded comments. Some of this does not
80 survive so well. Especially some of the examples that are longer than 80
81 characters. The build process for this file outputs to <tt class=
82 "FILENAME">config.new</tt>, which should be reviewed for errors and
83 mis-formatting. Once satisfied that it is correct, then it should be hand
84 copied to <tt class="FILENAME">config</tt>.</p>
86 <p>Other, less formal documents (e.g. <tt class="FILENAME">LICENSE</tt>)
87 are maintained as plain text files in the top-level source directory.</p>
89 <p>Packagers are encouraged to include this documentation. For those
90 without the ability to build the docs locally, text versions of each are
91 kept in CVS. HTML versions are also being kept in CVS under <tt class=
92 "FILENAME">doc/webserver/*</tt>. And PDF version are kept in <tt class=
93 "FILENAME">doc/pdf/*</tt>.</p>
95 <p>Formal documents are built with the Makefile targets of <samp class=
96 "COMPUTEROUTPUT">make dok</samp>, or alternately <samp class=
97 "COMPUTEROUTPUT">make redhat-dok</samp>. If you have problems, try both.
98 The build process uses the document SGML sources in <samp class=
99 "COMPUTEROUTPUT">doc/source/*/*</samp> to update all text files in
100 <samp class="COMPUTEROUTPUT">doc/text/</samp> and to update all HTML
101 documents in <samp class="COMPUTEROUTPUT">doc/webserver/</samp>.</p>
103 <p>Documentation writers should please make sure documents build
104 successfully before committing to CVS, if possible.</p>
106 <p>How do you update the webserver (i.e. the pages on privoxy.org)?</p>
110 <p>First, build the docs by running <samp class="COMPUTEROUTPUT">make
111 dok</samp> (or alternately <samp class="COMPUTEROUTPUT">make
112 redhat-dok</samp>). For PDF docs, do <samp class=
113 "COMPUTEROUTPUT">make dok-pdf</samp>.</p>
117 <p>Run <samp class="COMPUTEROUTPUT">make webserver</samp> which
118 copies all files from <samp class=
119 "COMPUTEROUTPUT">doc/webserver</samp> to the sourceforge webserver
124 <p>Finished docs should be occasionally submitted to CVS (<tt class=
125 "FILENAME">doc/webserver/*/*.html</tt>) so that those without the ability
126 to build them locally, have access to them if needed. This is especially
127 important just prior to a new release! Please do this <span class=
128 "emphasis EMPHASIS c3">after</span> the <tt class="LITERAL">$VERSION</tt>
129 and other release specific data in <tt class="FILENAME">configure.in</tt>
130 has been updated (this is done just prior to a new release).</p>
133 <h2 class="SECT2"><a name="SGML" id="SGML">3.1. Quickstart to Docbook
136 <p>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 used
138 to define markup languages. In fact, HTML is an SGML application. Both
139 will use <span class="QUOTE">"tags"</span> to format text and other
140 content. SGML tags can be much more varied, and flexible, but do much
141 of the same kinds of things. The tags, or <span class=
142 "QUOTE">"elements"</span>, are definable in SGML. There is no set
143 <span class="QUOTE">"standards"</span>. Since we are using <span class=
144 "APPLICATION">Docbook</span>, our tags are those that are defined by
145 <span class="APPLICATION">Docbook</span>. Much of how the finish
146 document is rendered is determined by the <span class=
147 "QUOTE">"stylesheets"</span>. The stylesheets determine how each tag
148 gets translated to HTML, or other formats.</p>
150 <p>Tags in Docbook SGML need to be always <span class=
151 "QUOTE">"closed"</span>. If not, you will likely generate errors.
152 Example: <tt class="LITERAL"><title>My Title</title></tt>.
153 They are also case-insensitive, but we strongly suggest using all lower
154 case. This keeps compatibility with [Docbook] <span class=
155 "APPLICATION">XML</span>.</p>
157 <p>Our documents use <span class="QUOTE">"sections"</span> for the most
158 part. Sections will be processed into HTML headers (e.g. <tt class=
159 "LITERAL">h1</tt> for <tt class="LITERAL">sect1</tt>). The <span class=
160 "APPLICATION">Docbook</span> stylesheets will use these to also
161 generate the Table of Contents for each doc. Our TOC's are set to a
162 depth of three. Meaning <tt class="LITERAL">sect1</tt>, <tt class=
163 "LITERAL">sect2</tt>, and <tt class="LITERAL">sect3</tt> will have TOC
164 entries, but <tt class="LITERAL">sect4</tt> will not. Each section
165 requires a <tt class="LITERAL"><title></tt> element, and at least
166 one <tt class="LITERAL"><para></tt>. There is a limit of five
167 section levels in Docbook, but generally three should be sufficient for
170 <p>Some common elements that you likely will use:</p>
176 "emphasis EMPHASIS c3"><para></para></span>,
177 paragraph delimiter. Most text needs to be within paragraph
178 elements (there are some exceptions).</td>
183 "emphasis EMPHASIS c3"><emphasis></emphasis></span>,
184 the stylesheets make this italics.</td>
189 "emphasis EMPHASIS c3"><filename></filename></span>,
190 files and directories.</td>
195 "emphasis EMPHASIS c3"><command></command></span>,
196 command examples.</td>
201 "emphasis EMPHASIS c3"><literallayout></literallayout></span>,
202 like <tt class="LITERAL"><pre></tt>, more or less.</td>
207 "emphasis EMPHASIS c3"><itemizedlist></itemizedlist></span>,
208 list with bullets.</td>
213 "emphasis EMPHASIS c3"><listitem></listitem></span>,
214 member of the above.</td>
219 "emphasis EMPHASIS c3"><screen></screen></span>,
220 screen output, implies <tt class=
221 "LITERAL"><literallayout></tt>.</td>
225 <td><span class="emphasis EMPHASIS c3"><ulink
226 url="example.com"></ulink></span>, like HTML <tt class=
227 "LITERAL"><a></tt> tag.</td>
232 "emphasis EMPHASIS c3"><quote></quote></span>, for,
233 doh, quoting text.</td>
238 <p>Look at any of the existing docs for examples of all these and
241 <p>You might also find <span class="QUOTE">"<a href=
242 "http://opensource.bureau-cornavin.com/crash-course/index.html" target=
243 "_top">Writing Documentation Using DocBook - A Crash Course</a>"</span>
248 <h2 class="SECT2"><a name="DOCSTYLE" id="DOCSTYLE">3.2. <span class=
249 "APPLICATION">Privoxy</span> Documentation Style</a></h2>
251 <p>It will be easier if everyone follows a similar writing style. This
252 just makes it easier to read what someone else has written if it is all
253 done in a similar fashion.</p>
259 <p>All tags should be lower case.</p>
263 <p>Tags delimiting a <span class=
264 "emphasis EMPHASIS c3">block</span> of text (even small blocks)
265 should be on their own line. Like:</p>
267 <p class="LITERALLAYOUT"> <para><br>
268 Some text goes here.<br>
269 </para><br>
270 </p>Tags marking
271 individual words, or few words, should be in-line:
273 <p class="LITERALLAYOUT">
274 Just to <emphasis>emphasize</emphasis>, some text goes here.<br>
276 </p>
280 <p>Tags should be nested and step indented for block text like:
281 (except in-line tags)</p>
283 <p class="LITERALLAYOUT"> <para><br>
284 <itemizedlist><br>
285 <para><br>
286 <listitem><br>
287 Some text goes here in our list example.<br>
289 </listitem><br>
290 </para><br>
291 </itemizedlist><br>
292 </para><br>
293 </p>This makes it easier
294 to find the text amongst the tags ;-)
298 <p>Use white space to separate logical divisions within a document,
299 like between sections. Running everything together consistently
300 makes it harder to read and work on.</p>
304 <p>Do not hesitate to make comments. Comments can either use the
305 <comment> element, or the <!-- --> style comment
306 familiar from HTML. (Note in Docbook v4.x <comment> is
307 replaced by <remark>.)</p>
311 <p>We have an international audience. Refrain from slang, or
312 English idiosyncrasies (too many to list :). Humor also does not
313 translate well sometimes.</p>
317 <p>Try to keep overall line lengths in source files to 80
318 characters or less for obvious reasons. This is not always
319 possible, with lengthy URLs for instance.</p>
323 <p>Our documents are available in differing formats. Right now,
324 they are just plain text, HTML, and PDF, but others are always a
325 future possibility. Be careful with URLs (<ulink>), and avoid
328 <p>My favorite site is <ulink
329 url="http://example.com">here</ulink>.</p>
331 <p>This will render as <span class="QUOTE">"My favorite site is
332 here"</span>, which is not real helpful in a text doc. Better like
335 <p>My favorite site is <ulink
336 url="http://example.com">example.com</ulink>.</p>
340 <p>All documents should be spell checked occasionally. <span class=
341 "APPLICATION">aspell</span> can check SGML with the <tt class=
342 "LITERAL">-H</tt> option. (<span class="APPLICATION">ispell</span>
349 <h2 class="SECT2"><a name="AEN217" id="AEN217">3.3. Privoxy Custom
352 <p><span class="APPLICATION">Privoxy</span> documentation is using a
353 number of customized <span class="QUOTE">"entities"</span> to
354 facilitate documentation maintenance.</p>
356 <p>We are using a set of <span class="QUOTE">"boilerplate"</span> files
357 with generic text, that is used by multiple docs. This way we can write
358 something once, and use it repeatedly without having to re-write the
359 same content over and over again. If editing such a file, keep in mind
360 that it should be <span class="emphasis EMPHASIS c3">generic</span>.
361 That is the purpose; so it can be used in varying contexts without
362 additional modifications.</p>
364 <p>We are also using what <span class="APPLICATION">Docbook</span>
365 calls <span class="QUOTE">"internal entities"</span>. These are like
366 variables in programming. Well, sort of. For instance, we have the
367 <tt class="LITERAL">p-version</tt> entity that contains the current
368 <span class="APPLICATION">Privoxy</span> version string. You are
369 strongly encouraged to use these where possible. Some of these
370 obviously require re-setting with each release (done by the Makefile).
371 A sampling of custom entities are listed below. See any of the main
372 docs for examples.</p>
376 <p>Re- <span class="QUOTE">"boilerplate"</span> text entities are
379 <p><tt class="LITERAL"><!entity supported SYSTEM
380 "supported.sgml"></tt></p>
382 <p>In this example, the contents of the file, <tt class=
383 "FILENAME">supported.sgml</tt> is available for inclusion anywhere
384 in the doc. To make this happen, just reference the now defined
385 entity: <tt class="LITERAL">&supported;</tt> (starts with an
386 ampersand and ends with a semi-colon), and the contents will be
387 dumped into the finished doc at that point.</p>
391 <p>Commonly used <span class="QUOTE">"internal
392 entities"</span>:</p>
397 <td><span class="emphasis EMPHASIS c3">p-version</span>: the
398 <span class="APPLICATION">Privoxy</span> version string, e.g.
399 <span class="QUOTE">"3.0.20"</span>.</td>
403 <td><span class="emphasis EMPHASIS c3">p-status</span>: the
404 project status, either <span class="QUOTE">"alpha"</span>,
405 <span class="QUOTE">"beta"</span>, or <span class=
406 "QUOTE">"stable"</span>.</td>
410 <td><span class="emphasis EMPHASIS c3">p-not-stable</span>:
411 use to conditionally include text in <span class="QUOTE">"not
412 stable"</span> releases (e.g. <span class=
413 "QUOTE">"beta"</span>).</td>
417 <td><span class="emphasis EMPHASIS c3">p-stable</span>: just
422 <td><span class="emphasis EMPHASIS c3">p-text</span>: this
423 doc is only generated as text.</td>
430 <p>There are others in various places that are defined for a specific
431 purpose. Read the source!</p>
435 <div class="NAVFOOTER">
436 <hr class="c1" width="100%">
438 <table summary="Footer navigation table" width="100%" border="0"
439 cellpadding="0" cellspacing="0">
441 <td width="33%" align="left" valign="top"><a href="cvs.html"
442 accesskey="P">Prev</a></td>
444 <td width="34%" align="center" valign="top"><a href="index.html"
445 accesskey="H">Home</a></td>
447 <td width="33%" align="right" valign="top"><a href="coding.html"
448 accesskey="N">Next</a></td>
452 <td width="33%" align="left" valign="top">The CVS Repository</td>
454 <td width="34%" align="center" valign="top"> </td>
456 <td width="33%" align="right" valign="top">Coding Guidelines</td>