All formal documents are maintained in docbook SGML and located in the +> All formal documents are maintained in Docbook SGML and located in the doc/sourcedoc/source/* directory. You will need docbook and the docbook - stylesheets (or comparable alternatives), and either - Docbook, the Docbook + DTD's and the Docbook modular stylesheets (or comparable alternatives), + and either jade or or + openjade - (recommended) installed in order to build docs from source. Currently - there is (recommended) installed in order to + build docs from source. Currently there is FAQ, and, - of course this, the , and, of + course this, the developer-manual in this - format. The in this format. + The README, is also now maintained - as SGML. The , README in the top-level source - directory is a generated file. AUTHORS + privoxy.1 (man page) files are also now maintained + as Docbook SGML. The finished files are all in the top-level source + directory are generated files! Also, index.html, the + Privoxy home page, is maintained as SGML. + DO NOT edit this - directly. Edit the SGML source! +>DO NOT edit these directly. Edit the SGML source, or + contact someone involved in the documentation (at present Stefan and + Hal).
Other, less formal documents (e.g. AUTHORS, LICENSE) are maintained as - plain text files in the toplevel source directory. At least for the - time being. +> Other, less formal documents (e.g. LICENSE, + INSTALL) are maintained as plain text files in the + top-level source directory. At least for the time being.
Packagers are encouraged to include this documentation. For those without the ability to build the docs locally, text versions of each are kept in - CVS. Or HTML versions can be downloaded from the www.privoxy.org website, which - should be fairly current. (This is only a temporary solution.) + CVS. HTML versions are also now being kept in CVS under + doc/webserver/*.
Formal documents are built with the Makefile targets of @@ -154,20 +173,20 @@ CLASS="COMPUTEROUTPUT" try both. The build process uses the document SGML sources in doc/sourcedoc/source/*/* to update all text files in doc/textdoc/text/ and to update all HTML documents in doc/webserverdoc/webserver/.
Documentation writers should please make sure documents build - successfully before committing to CVS. + successfully before committing to CVS, if possible.
How do you update the webserver (i.e. the pages on privoxy.org)? @@ -205,56 +224,78 @@ CLASS="COMPUTEROUTPUT" >
Finished docs should be occasionally submitted to CVS + (doc/webserver/*/*.html) so that those without + the ability to build them locally, have access to them if needed. + This is especially important just prior to a new release! Please + do this after the $VERSION and + other release specific data in configure.in has been + updated (this is done just prior to a new release). +
If you are not familiar with SGML, it is a markup language similar to HTML. - In fact, HTML is an SGML application. Both use "tags" - to format text and other content. SGML tags are much more varied, - and flexible, but do much of the same kinds of things. The tags, +> to format text and other content. SGML tags can be much + more varied, and flexible, but do much of the same kinds of things. The tags, or "elements", are definable in SGML. There is no - set , are definable in SGML. There is no set + "standards". Since we are using Docbook, our tags are those that are - defined by , our tags are those that are defined by + Docbook. Much of how the - finish document is rendered is determined by the . Much of how the finish document is + rendered is determined by the "stylesheets". - The stylesheets determine how each tag gets translated to HTML, or - other formats.
Tags in SGML need to be always Tags in Docbook SGML need to be always "closed". If not, you - will likely generate errors. Example: - . If not, you + will likely generate errors. Example: <title>My Title</title>. They are - also case-insensitive, but we strongly suggest using all lower - case. This keeps compatibility with [Docbook] <title>My + Title</title>. They are also case-insensitive, but we + strongly suggest using all lower case. This keeps compatibility with + [Docbook] XML.
Some common elements that you likely will use:
| <para></para>, paragraph delimiter. Most - text needs to be within paragraph elements. - |
| <emphasis></emphasis>, stylesheets make this - italics. - | , the stylesheets + make this italics. +
| <filename></filename>, files and directories. - |
| <command></command>, command examples. - |
| <literallayout></literllayout><literallayout></literallayout>, like - <pre>, more or less. - |
| <itemizedlist></itemizdelist><itemizedlist></itemizedlist>, list with bullets. - |
| <listitem></listitem>, member of the above. - |
| <screen></screen>, screen output, implies - <literallayout>. - |
| <ulink url="example.com"></ulink>, like - HTML <a> tag. - |
| <quote></quote>, for, doh, quoting text. - |
Look at any of the existing docs for examples of all these and more.
You might also find "Writing Documentation + Using DocBook - A Crash Course" useful.
Tags delimiting a block of text should be on their own line. - Like: +> Tags delimiting a block of text (even small + blocks) should be on their own line. Like:
<para>
@@ -457,8 +513,9 @@ CLASS="LITERALLAYOUT"
>
Tags should be nested and step indented like: -
Tags should be nested and step indented for block text like: (except + in-line tags) +
<para>
<itemizedlist>
@@ -485,19 +542,21 @@ CLASS="LITERALLAYOUT"
>
Do not hesitate to make comments. Comments can either use the <comment> element, or the <!-- --> style comment - familiar from HTML. + familiar from HTML. (Note in Docbook v4.x <comment> is + replaced by <remark>.)
We have an international audience. Refrain from slang, or English - idiosyncrasies (too many to list :). + idiosyncrasies (too many to list :). Humor also does not translate + well sometimes.
Try to keep overall line lengths in source files to 80 characters or less - for obvious reasons. This is not always possible, with lenghty URLs for + for obvious reasons. This is not always possible, with lengthy URLs for instance.
Privoxy version string. You are strongly encouraged to use these where possible. Some of these obviously - require re-setting with each release. A sampling of custom entities are - listed below. See any of the main docs for examples. + require re-setting with each release (done by the Makefile). A sampling of + custom entities are listed below. See any of the main docs for examples.
Re-cyclable Re- "boilerplate" text entities are defined like: @@ -653,7 +712,7 @@ CLASS="APPLICATION" > version string, e.g. "2.9.13""2.9.14".