1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
2 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
6 Documentation Guidelines
8 <meta name="GENERATOR" content=
9 "Modular DocBook HTML Stylesheet Version 1.79">
10 <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
11 <link rel="PREVIOUS" title="The CVS Repository" href="cvs.html">
12 <link rel="NEXT" title="Coding Guidelines" href="coding.html">
13 <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
14 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
16 <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
17 "#840084" alink="#0000FF">
18 <div class="NAVHEADER">
19 <table summary="Header navigation table" width="100%" border="0"
20 cellpadding="0" cellspacing="0">
22 <th colspan="3" align="center">
23 Privoxy Developer Manual
27 <td width="10%" align="left" valign="bottom">
28 <a href="cvs.html" accesskey="P">Prev</a>
30 <td width="80%" align="center" valign="bottom">
32 <td width="10%" align="right" valign="bottom">
33 <a href="coding.html" accesskey="N">Next</a>
37 <hr align="LEFT" width="100%">
41 <a name="DOCUMENTATION">3. Documentation Guidelines</a>
44 All formal documents are maintained in Docbook SGML and located in
45 the <samp class="COMPUTEROUTPUT">doc/source/*</samp> directory. You
46 will need <a href="http://www.docbook.org" target="_top">Docbook</a>,
47 the Docbook DTD's and the Docbook modular stylesheets (or comparable
48 alternatives), and either <span class="APPLICATION">jade</span> or
49 <span class="APPLICATION">openjade</span> (recommended) installed in
50 order to build docs from source. Currently there is <a href=
51 "../user-manual/index.html" target="_top"><i class=
52 "CITETITLE">user-manual</i></a>, <a href="../faq/index.html" target=
53 "_top"><i class="CITETITLE">FAQ</i></a>, and, of course this, the <i
54 class="CITETITLE">developer-manual</i> in this format. The <i class=
55 "CITETITLE">README</i>, <i class="CITETITLE">AUTHORS</i>, <i class=
56 "CITETITLE">INSTALL</i>, <i class="CITETITLE">privoxy.1</i> (man
57 page), and <i class="CITETITLE">config</i> files are also now
58 maintained as Docbook SGML. These files, when built, in the top-level
59 source directory are generated files! Also, the <span class=
60 "APPLICATION">Privoxy</span> <tt class="FILENAME">index.html</tt>
61 (and a variation on this file, <tt class=
62 "FILENAME">privoxy-index.html</tt>, meant for inclusion with doc
63 packages), are maintained as SGML as well. <span class="emphasis"><i
64 class="EMPHASIS">DO NOT edit these directly</i></span>. Edit the SGML
65 source, or contact someone involved in the documentation.
68 <tt class="FILENAME">config</tt> requires some special handling. The
69 reason it is maintained this way is so that the extensive comments in
70 the file mirror those in <i class="CITETITLE">user-manual</i>. But
71 the conversion process requires going from SGML to HTML to text to
72 special formatting required for the embedded comments. Some of this
73 does not survive so well. Especially some of the examples that are
74 longer than 80 characters. The build process for this file outputs to
75 <tt class="FILENAME">config.new</tt>, which should be reviewed for
76 errors and mis-formatting. Once satisfied that it is correct, then it
77 should be hand copied to <tt class="FILENAME">config</tt>.
80 Other, less formal documents (e.g. <tt class="FILENAME">LICENSE</tt>)
81 are maintained as plain text files in the top-level source directory.
84 Packagers are encouraged to include this documentation. For those
85 without the ability to build the docs locally, text versions of each
86 are kept in CVS. HTML versions are also being kept in CVS under <tt
87 class="FILENAME">doc/webserver/*</tt>.
90 Formal documents are built with the Makefile targets of <samp class=
91 "COMPUTEROUTPUT">make dok</samp>. The build process uses the document
92 SGML sources in <samp class="COMPUTEROUTPUT">doc/source/*/*</samp> to
93 update all text files in <samp class=
94 "COMPUTEROUTPUT">doc/text/</samp> and to update all HTML documents in
95 <samp class="COMPUTEROUTPUT">doc/webserver/</samp>.
98 Documentation writers should please make sure documents build
99 successfully before committing to CVS, if possible.
102 How do you update the webserver (i.e. the pages on privoxy.org)?
107 First, build the docs by running <samp class=
108 "COMPUTEROUTPUT">make dok</samp>.
113 Run <samp class="COMPUTEROUTPUT">make webserver</samp> which
114 copies all files from <samp class=
115 "COMPUTEROUTPUT">doc/webserver</samp> to the sourceforge
122 Finished docs should be occasionally submitted to CVS (<tt class=
123 "FILENAME">doc/webserver/*/*.html</tt>) so that those without the
124 ability to build them locally, have access to them if needed. This is
125 especially important just prior to a new release! Please do this
126 <span class="emphasis"><i class="EMPHASIS">after</i></span> the <tt
127 class="LITERAL">$VERSION</tt> and other release specific data in <tt
128 class="FILENAME">configure.in</tt> has been updated (this is done
129 just prior to a new release).
133 <a name="SGML">3.1. Quickstart to Docbook and SGML</a>
136 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
138 used to define markup languages. In fact, HTML is an SGML
139 application. Both will use <span class="QUOTE">"tags"</span> to
140 format text and other content. SGML tags can be much more varied,
141 and flexible, but do much of the same kinds of things. The tags, or
142 <span class="QUOTE">"elements"</span>, are definable in SGML. There
143 is no set <span class="QUOTE">"standards"</span>. Since we are
144 using <span class="APPLICATION">Docbook</span>, our tags are those
145 that are defined by <span class="APPLICATION">Docbook</span>. Much
146 of how the finish document is rendered is determined by the <span
147 class="QUOTE">"stylesheets"</span>. The stylesheets determine how
148 each tag gets translated to HTML, or other formats.
151 Tags in Docbook SGML need to be always <span class=
152 "QUOTE">"closed"</span>. If not, you will likely generate errors.
153 Example: <tt class="LITERAL"><title>My
154 Title</title></tt>. They are also case-insensitive, but we
155 strongly suggest using all lower case. This keeps compatibility
156 with [Docbook] <span class="APPLICATION">XML</span>.
159 Our documents use <span class="QUOTE">"sections"</span> for the
160 most part. Sections will be processed into HTML headers (e.g. <tt
161 class="LITERAL">h1</tt> for <tt class="LITERAL">sect1</tt>). The
162 <span class="APPLICATION">Docbook</span> stylesheets will use these
163 to also generate the Table of Contents for each doc. Our TOC's are
164 set to a depth of three. Meaning <tt class="LITERAL">sect1</tt>,
165 <tt class="LITERAL">sect2</tt>, and <tt class="LITERAL">sect3</tt>
166 will have TOC entries, but <tt class="LITERAL">sect4</tt> will not.
167 Each section requires a <tt class="LITERAL"><title></tt>
168 element, and at least one <tt class="LITERAL"><para></tt>.
169 There is a limit of five section levels in Docbook, but generally
170 three should be sufficient for our purposes.
173 Some common elements that you likely will use:
181 <span class="emphasis"><i class=
182 "EMPHASIS"><para></para></i></span>, paragraph
183 delimiter. Most text needs to be within paragraph elements
184 (there are some exceptions).
189 <span class="emphasis"><i class=
190 "EMPHASIS"><emphasis></emphasis></i></span>, the
191 stylesheets make this italics.
196 <span class="emphasis"><i class=
197 "EMPHASIS"><filename></filename></i></span>,
198 files and directories.
203 <span class="emphasis"><i class=
204 "EMPHASIS"><command></command></i></span>,
210 <span class="emphasis"><i class=
211 "EMPHASIS"><literallayout></literallayout></i></span>,
212 like <tt class="LITERAL"><pre></tt>, more or less.
217 <span class="emphasis"><i class=
218 "EMPHASIS"><itemizedlist></itemizedlist></i></span>,
224 <span class="emphasis"><i class=
225 "EMPHASIS"><listitem></listitem></i></span>,
231 <span class="emphasis"><i class=
232 "EMPHASIS"><screen></screen></i></span>, screen
233 output, implies <tt class=
234 "LITERAL"><literallayout></tt>.
239 <span class="emphasis"><i class="EMPHASIS"><ulink
240 url="example.com"></ulink></i></span>, like HTML <tt
241 class="LITERAL"><a></tt> tag.
246 <span class="emphasis"><i class=
247 "EMPHASIS"><quote></quote></i></span>, for, doh,
255 Look at any of the existing docs for examples of all these and
259 You might also find <span class="QUOTE">"<a href=
260 "http://opensource.bureau-cornavin.com/crash-course/index.html"
261 target="_top">Writing Documentation Using DocBook - A Crash
262 Course</a>"</span> useful.
267 <a name="DOCSTYLE">3.2. <span class="APPLICATION">Privoxy</span>
268 Documentation Style</a>
271 It will be easier if everyone follows a similar writing style. This
272 just makes it easier to read what someone else has written if it is
273 all done in a similar fashion.
283 All tags should be lower case.
288 Tags delimiting a <span class="emphasis"><i class=
289 "EMPHASIS">block</i></span> of text (even small blocks) should
290 be on their own line. Like:
292 <p class="LITERALLAYOUT">
293 <para><br>
294 Some text goes here.<br>
295 </para><br>
296
298 Tags marking individual words, or few words, should be in-line:
299 <p class="LITERALLAYOUT">
300 Just to <emphasis>emphasize</emphasis>, some text goes here.<br>
302
307 Tags should be nested and step indented for block text like:
308 (except in-line tags)
310 <p class="LITERALLAYOUT">
311 <para><br>
312 <itemizedlist><br>
313 <para><br>
314 <listitem><br>
315 Some text goes here in our list example.<br>
317 </listitem><br>
318 </para><br>
319 </itemizedlist><br>
320 </para><br>
321
323 This makes it easier to find the text amongst the tags ;-)<br>
327 Use white space to separate logical divisions within a
328 document, like between sections. Running everything together
329 consistently makes it harder to read and work on.
334 Do not hesitate to make comments. Comments can either use the
335 <comment> element, or the <!-- --> style comment
336 familiar from HTML. (Note in Docbook v4.x <comment> is
337 replaced by <remark>.)
342 We have an international audience. Refrain from slang, or
343 English idiosyncrasies (too many to list :). Humor also does
344 not translate well sometimes.
349 Try to keep overall line lengths in source files to 80
350 characters or less for obvious reasons. This is not always
351 possible, with lengthy URLs for instance.
356 Our documents are available in differing formats. Right now,
357 they are just plain text and/or HTML, but others are always a
358 future possibility. Be careful with URLs (<ulink>), and
362 My favorite site is <ulink
363 url="http://example.com">here</ulink>.
366 This will render as <span class="QUOTE">"My favorite site is
367 here"</span>, which is not real helpful in a text doc. Better
371 My favorite site is <ulink
372 url="http://example.com">example.com</ulink>.
377 All documents should be spell checked occasionally. <span
378 class="APPLICATION">aspell</span> can check SGML with the <tt
379 class="LITERAL">-H</tt> option. (<span class=
380 "APPLICATION">ispell</span> I think too.)
387 <a name="AEN207">3.3. Privoxy Custom Entities</a>
390 <span class="APPLICATION">Privoxy</span> documentation is using a
391 number of customized <span class="QUOTE">"entities"</span> to
392 facilitate documentation maintenance.
395 We are using a set of <span class="QUOTE">"boilerplate"</span>
396 files with generic text, that is used by multiple docs. This way we
397 can write something once, and use it repeatedly without having to
398 re-write the same content over and over again. If editing such a
399 file, keep in mind that it should be <span class="emphasis"><i
400 class="EMPHASIS">generic</i></span>. That is the purpose; so it can
401 be used in varying contexts without additional modifications.
404 We are also using what <span class="APPLICATION">Docbook</span>
405 calls <span class="QUOTE">"internal entities"</span>. These are
406 like variables in programming. Well, sort of. For instance, we have
407 the <tt class="LITERAL">p-version</tt> entity that contains the
408 current <span class="APPLICATION">Privoxy</span> version string.
409 You are strongly encouraged to use these where possible. Some of
410 these obviously require re-setting with each release (done by the
411 Makefile). A sampling of custom entities are listed below. See any
412 of the main docs for examples.
419 Re- <span class="QUOTE">"boilerplate"</span> text entities are
423 <tt class="LITERAL"><!entity supported SYSTEM
424 "supported.sgml"></tt>
427 In this example, the contents of the file, <tt class=
428 "FILENAME">supported.sgml</tt> is available for inclusion
429 anywhere in the doc. To make this happen, just reference the
430 now defined entity: <tt class="LITERAL">&supported;</tt>
431 (starts with an ampersand and ends with a semi-colon), and the
432 contents will be dumped into the finished doc at that point.
437 Commonly used <span class="QUOTE">"internal entities"</span>:
443 <span class="emphasis"><i class=
444 "EMPHASIS">p-version</i></span>: the <span class=
445 "APPLICATION">Privoxy</span> version string, e.g. <span
446 class="QUOTE">"3.0.25"</span>.
451 <span class="emphasis"><i class=
452 "EMPHASIS">p-status</i></span>: the project status,
453 either <span class="QUOTE">"alpha"</span>, <span class=
454 "QUOTE">"beta"</span>, or <span class=
455 "QUOTE">"stable"</span>.
460 <span class="emphasis"><i class=
461 "EMPHASIS">p-not-stable</i></span>: use to conditionally
462 include text in <span class="QUOTE">"not stable"</span>
463 releases (e.g. <span class="QUOTE">"beta"</span>).
468 <span class="emphasis"><i class=
469 "EMPHASIS">p-stable</i></span>: just the opposite.
474 <span class="emphasis"><i class=
475 "EMPHASIS">p-text</i></span>: this doc is only generated
485 There are others in various places that are defined for a specific
486 purpose. Read the source!
490 <div class="NAVFOOTER">
491 <hr align="LEFT" width="100%">
492 <table summary="Footer navigation table" width="100%" border="0"
493 cellpadding="0" cellspacing="0">
495 <td width="33%" align="left" valign="top">
496 <a href="cvs.html" accesskey="P">Prev</a>
498 <td width="34%" align="center" valign="top">
499 <a href="index.html" accesskey="H">Home</a>
501 <td width="33%" align="right" valign="top">
502 <a href="coding.html" accesskey="N">Next</a>
506 <td width="33%" align="left" valign="top">
509 <td width="34%" align="center" valign="top">
512 <td width="33%" align="right" valign="top">