1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
2 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
5 <meta name="generator" content="HTML Tidy, see www.w3.org">
7 Documentation Guidelines
9 <meta name="GENERATOR" content=
10 "Modular DocBook HTML Stylesheet Version 1.79">
11 <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
12 <link rel="PREVIOUS" title="The CVS Repository" href="cvs.html">
13 <link rel="NEXT" title="Coding Guidelines" href="coding.html">
14 <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
15 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
16 <style type="text/css">
18 background-color: #EEEEEE;
21 :link { color: #0000FF }
22 :visited { color: #840084 }
23 :active { color: #0000FF }
24 hr.c1 {text-align: left}
28 <div class="NAVHEADER">
29 <table summary="Header navigation table" width="100%" border="0"
30 cellpadding="0" cellspacing="0">
32 <th colspan="3" align="center">
33 Privoxy Developer Manual
37 <td width="10%" align="left" valign="bottom">
38 <a href="cvs.html" accesskey="P">Prev</a>
40 <td width="80%" align="center" valign="bottom">
42 <td width="10%" align="right" valign="bottom">
43 <a href="coding.html" accesskey="N">Next</a>
47 <hr width="100%" class="c1">
51 <a name="DOCUMENTATION">3. Documentation Guidelines</a>
54 All formal documents are maintained in Docbook SGML and located in
55 the <samp class="COMPUTEROUTPUT">doc/source/*</samp> directory. You
56 will need <a href="http://www.docbook.org" target="_top">Docbook</a>,
57 the Docbook DTD's and the Docbook modular stylesheets (or comparable
58 alternatives), and either <span class="APPLICATION">jade</span> or
59 <span class="APPLICATION">openjade</span> (recommended) installed in
60 order to build docs from source. Currently there is <a href=
61 "../user-manual/index.html" target="_top"><i class=
62 "CITETITLE">user-manual</i></a>, <a href="../faq/index.html" target=
63 "_top"><i class="CITETITLE">FAQ</i></a>, and, of course this, the <i
64 class="CITETITLE">developer-manual</i> in this format. The <i class=
65 "CITETITLE">README</i>, <i class="CITETITLE">AUTHORS</i>, <i class=
66 "CITETITLE">INSTALL</i>, <i class="CITETITLE">privoxy.1</i> (man
67 page), and <i class="CITETITLE">config</i> files are also now
68 maintained as Docbook SGML. These files, when built, in the top-level
69 source directory are generated files! Also, the <span class=
70 "APPLICATION">Privoxy</span> <tt class="FILENAME">index.html</tt>
71 (and a variation on this file, <tt class=
72 "FILENAME">privoxy-index.html</tt>, meant for inclusion with doc
73 packages), are maintained as SGML as well. <span class="emphasis"><i
74 class="EMPHASIS">DO NOT edit these directly</i></span>. Edit the SGML
75 source, or contact someone involved in the documentation.
78 <tt class="FILENAME">config</tt> requires some special handling. The
79 reason it is maintained this way is so that the extensive comments in
80 the file mirror those in <i class="CITETITLE">user-manual</i>. But
81 the conversion process requires going from SGML to HTML to text to
82 special formatting required for the embedded comments. Some of this
83 does not survive so well. Especially some of the examples that are
84 longer than 80 characters. The build process for this file outputs to
85 <tt class="FILENAME">config.new</tt>, which should be reviewed for
86 errors and mis-formatting. Once satisfied that it is correct, then it
87 should be hand copied to <tt class="FILENAME">config</tt>.
90 Other, less formal documents (e.g. <tt class="FILENAME">LICENSE</tt>)
91 are maintained as plain text files in the top-level source directory.
94 Packagers are encouraged to include this documentation. For those
95 without the ability to build the docs locally, text versions of each
96 are kept in CVS. HTML versions are also being kept in CVS under <tt
97 class="FILENAME">doc/webserver/*</tt>. And PDF version are kept in
98 <tt class="FILENAME">doc/pdf/*</tt>.
101 Formal documents are built with the Makefile targets of <samp class=
102 "COMPUTEROUTPUT">make dok</samp>, or alternately <samp class=
103 "COMPUTEROUTPUT">make redhat-dok</samp>. If you have problems, try
104 both. The build process uses the document SGML sources in <samp
105 class="COMPUTEROUTPUT">doc/source/*/*</samp> to update all text files
106 in <samp class="COMPUTEROUTPUT">doc/text/</samp> and to update all
107 HTML documents in <samp class="COMPUTEROUTPUT">doc/webserver/</samp>.
110 Documentation writers should please make sure documents build
111 successfully before committing to CVS, if possible.
114 How do you update the webserver (i.e. the pages on privoxy.org)?
119 First, build the docs by running <samp class=
120 "COMPUTEROUTPUT">make dok</samp> (or alternately <samp class=
121 "COMPUTEROUTPUT">make redhat-dok</samp>). For PDF docs, do <samp
122 class="COMPUTEROUTPUT">make dok-pdf</samp>.
127 Run <samp class="COMPUTEROUTPUT">make webserver</samp> which
128 copies all files from <samp class=
129 "COMPUTEROUTPUT">doc/webserver</samp> to the sourceforge
136 Finished docs should be occasionally submitted to CVS (<tt class=
137 "FILENAME">doc/webserver/*/*.html</tt>) so that those without the
138 ability to build them locally, have access to them if needed. This is
139 especially important just prior to a new release! Please do this
140 <span class="emphasis"><i class="EMPHASIS">after</i></span> the <tt
141 class="LITERAL">$VERSION</tt> and other release specific data in <tt
142 class="FILENAME">configure.in</tt> has been updated (this is done
143 just prior to a new release).
147 <a name="SGML">3.1. Quickstart to Docbook and SGML</a>
150 If you are not familiar with SGML, it is a markup language similar
151 to HTML. Actually, not a mark up language per se, but a language
152 used to define markup languages. In fact, HTML is an SGML
153 application. Both will use <span class="QUOTE">"tags"</span> to
154 format text and other content. SGML tags can be much more varied,
155 and flexible, but do much of the same kinds of things. The tags, or
156 <span class="QUOTE">"elements"</span>, are definable in SGML. There
157 is no set <span class="QUOTE">"standards"</span>. Since we are
158 using <span class="APPLICATION">Docbook</span>, our tags are those
159 that are defined by <span class="APPLICATION">Docbook</span>. Much
160 of how the finish document is rendered is determined by the <span
161 class="QUOTE">"stylesheets"</span>. The stylesheets determine how
162 each tag gets translated to HTML, or other formats.
165 Tags in Docbook SGML need to be always <span class=
166 "QUOTE">"closed"</span>. If not, you will likely generate errors.
167 Example: <tt class="LITERAL"><title>My
168 Title</title></tt>. They are also case-insensitive, but we
169 strongly suggest using all lower case. This keeps compatibility
170 with [Docbook] <span class="APPLICATION">XML</span>.
173 Our documents use <span class="QUOTE">"sections"</span> for the
174 most part. Sections will be processed into HTML headers (e.g. <tt
175 class="LITERAL">h1</tt> for <tt class="LITERAL">sect1</tt>). The
176 <span class="APPLICATION">Docbook</span> stylesheets will use these
177 to also generate the Table of Contents for each doc. Our TOC's are
178 set to a depth of three. Meaning <tt class="LITERAL">sect1</tt>,
179 <tt class="LITERAL">sect2</tt>, and <tt class="LITERAL">sect3</tt>
180 will have TOC entries, but <tt class="LITERAL">sect4</tt> will not.
181 Each section requires a <tt class="LITERAL"><title></tt>
182 element, and at least one <tt class="LITERAL"><para></tt>.
183 There is a limit of five section levels in Docbook, but generally
184 three should be sufficient for our purposes.
187 Some common elements that you likely will use:
195 <span class="emphasis"><i class=
196 "EMPHASIS"><para></para></i></span>, paragraph
197 delimiter. Most text needs to be within paragraph elements
198 (there are some exceptions).
203 <span class="emphasis"><i class=
204 "EMPHASIS"><emphasis></emphasis></i></span>, the
205 stylesheets make this italics.
210 <span class="emphasis"><i class=
211 "EMPHASIS"><filename></filename></i></span>,
212 files and directories.
217 <span class="emphasis"><i class=
218 "EMPHASIS"><command></command></i></span>,
224 <span class="emphasis"><i class=
225 "EMPHASIS"><literallayout></literallayout></i></span>,
226 like <tt class="LITERAL"><pre></tt>, more or less.
231 <span class="emphasis"><i class=
232 "EMPHASIS"><itemizedlist></itemizedlist></i></span>,
238 <span class="emphasis"><i class=
239 "EMPHASIS"><listitem></listitem></i></span>,
245 <span class="emphasis"><i class=
246 "EMPHASIS"><screen></screen></i></span>, screen
247 output, implies <tt class=
248 "LITERAL"><literallayout></tt>.
253 <span class="emphasis"><i class="EMPHASIS"><ulink
254 url="example.com"></ulink></i></span>, like HTML <tt
255 class="LITERAL"><a></tt> tag.
260 <span class="emphasis"><i class=
261 "EMPHASIS"><quote></quote></i></span>, for, doh,
269 Look at any of the existing docs for examples of all these and
273 You might also find <span class="QUOTE">"<a href=
274 "http://opensource.bureau-cornavin.com/crash-course/index.html"
275 target="_top">Writing Documentation Using DocBook - A Crash
276 Course</a>"</span> useful.
281 <a name="DOCSTYLE">3.2. <span class="APPLICATION">Privoxy</span>
282 Documentation Style</a>
285 It will be easier if everyone follows a similar writing style. This
286 just makes it easier to read what someone else has written if it is
287 all done in a similar fashion.
297 All tags should be lower case.
302 Tags delimiting a <span class="emphasis"><i class=
303 "EMPHASIS">block</i></span> of text (even small blocks) should
304 be on their own line. Like:
306 <p class="LITERALLAYOUT">
307 <para><br>
308 Some text goes here.<br>
309 </para><br>
310
312 Tags marking individual words, or few words, should be in-line:
313 <p class="LITERALLAYOUT">
314 Just to <emphasis>emphasize</emphasis>, some text goes here.<br>
316
321 Tags should be nested and step indented for block text like:
322 (except in-line tags)
324 <p class="LITERALLAYOUT">
325 <para><br>
326 <itemizedlist><br>
327 <para><br>
328 <listitem><br>
329 Some text goes here in our list example.<br>
331 </listitem><br>
332 </para><br>
333 </itemizedlist><br>
334 </para><br>
335
337 This makes it easier to find the text amongst the tags ;-)<br>
341 Use white space to separate logical divisions within a
342 document, like between sections. Running everything together
343 consistently makes it harder to read and work on.
348 Do not hesitate to make comments. Comments can either use the
349 <comment> element, or the <!-- --> style comment
350 familiar from HTML. (Note in Docbook v4.x <comment> is
351 replaced by <remark>.)
356 We have an international audience. Refrain from slang, or
357 English idiosyncrasies (too many to list :). Humor also does
358 not translate well sometimes.
363 Try to keep overall line lengths in source files to 80
364 characters or less for obvious reasons. This is not always
365 possible, with lengthy URLs for instance.
370 Our documents are available in differing formats. Right now,
371 they are just plain text, HTML, and PDF, but others are always
372 a future possibility. Be careful with URLs (<ulink>), and
376 My favorite site is <ulink
377 url="http://example.com">here</ulink>.
380 This will render as <span class="QUOTE">"My favorite site is
381 here"</span>, which is not real helpful in a text doc. Better
385 My favorite site is <ulink
386 url="http://example.com">example.com</ulink>.
391 All documents should be spell checked occasionally. <span
392 class="APPLICATION">aspell</span> can check SGML with the <tt
393 class="LITERAL">-H</tt> option. (<span class=
394 "APPLICATION">ispell</span> I think too.)
401 <a name="AEN217">3.3. Privoxy Custom Entities</a>
404 <span class="APPLICATION">Privoxy</span> documentation is using a
405 number of customized <span class="QUOTE">"entities"</span> to
406 facilitate documentation maintenance.
409 We are using a set of <span class="QUOTE">"boilerplate"</span>
410 files with generic text, that is used by multiple docs. This way we
411 can write something once, and use it repeatedly without having to
412 re-write the same content over and over again. If editing such a
413 file, keep in mind that it should be <span class="emphasis"><i
414 class="EMPHASIS">generic</i></span>. That is the purpose; so it can
415 be used in varying contexts without additional modifications.
418 We are also using what <span class="APPLICATION">Docbook</span>
419 calls <span class="QUOTE">"internal entities"</span>. These are
420 like variables in programming. Well, sort of. For instance, we have
421 the <tt class="LITERAL">p-version</tt> entity that contains the
422 current <span class="APPLICATION">Privoxy</span> version string.
423 You are strongly encouraged to use these where possible. Some of
424 these obviously require re-setting with each release (done by the
425 Makefile). A sampling of custom entities are listed below. See any
426 of the main docs for examples.
433 Re- <span class="QUOTE">"boilerplate"</span> text entities are
437 <tt class="LITERAL"><!entity supported SYSTEM
438 "supported.sgml"></tt>
441 In this example, the contents of the file, <tt class=
442 "FILENAME">supported.sgml</tt> is available for inclusion
443 anywhere in the doc. To make this happen, just reference the
444 now defined entity: <tt class="LITERAL">&supported;</tt>
445 (starts with an ampersand and ends with a semi-colon), and the
446 contents will be dumped into the finished doc at that point.
451 Commonly used <span class="QUOTE">"internal entities"</span>:
457 <span class="emphasis"><i class=
458 "EMPHASIS">p-version</i></span>: the <span class=
459 "APPLICATION">Privoxy</span> version string, e.g. <span
460 class="QUOTE">"3.0.18"</span>.
465 <span class="emphasis"><i class=
466 "EMPHASIS">p-status</i></span>: the project status,
467 either <span class="QUOTE">"alpha"</span>, <span class=
468 "QUOTE">"beta"</span>, or <span class=
469 "QUOTE">"stable"</span>.
474 <span class="emphasis"><i class=
475 "EMPHASIS">p-not-stable</i></span>: use to conditionally
476 include text in <span class="QUOTE">"not stable"</span>
477 releases (e.g. <span class="QUOTE">"beta"</span>).
482 <span class="emphasis"><i class=
483 "EMPHASIS">p-stable</i></span>: just the opposite.
488 <span class="emphasis"><i class=
489 "EMPHASIS">p-text</i></span>: this doc is only generated
499 There are others in various places that are defined for a specific
500 purpose. Read the source!
504 <div class="NAVFOOTER">
505 <hr width="100%" class="c1">
506 <table summary="Footer navigation table" width="100%" border="0"
507 cellpadding="0" cellspacing="0">
509 <td width="33%" align="left" valign="top">
510 <a href="cvs.html" accesskey="P">Prev</a>
512 <td width="34%" align="center" valign="top">
513 <a href="index.html" accesskey="H">Home</a>
515 <td width="33%" align="right" valign="top">
516 <a href="coding.html" accesskey="N">Next</a>
520 <td width="33%" align="left" valign="top">
523 <td width="34%" align="center" valign="top">
526 <td width="33%" align="right" valign="top">