All formal documents are maintained in docbook SGML and located in the doc/source directory. You will need docbook and the docbook stylesheets (or comparable alternatives), and either jade or openjade (recommended) installed in order to build docs from source. Currently there is user-manual, FAQ, and, of course this, the developer-manual in this format. The README, is also now maintained as SGML. The README in the top-level source directory is a generated file. DO NOT edit this directly. Edit the SGML source!
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.
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.)
Formal documents are built with the Makefile targets of make dok, or alternately make redhat-dok. If you have problems, try both. The build process uses the document SGML sources in doc/source to update all text files in doc/text and to update all HTML documents in doc/webserver.
Documentation writers should please make sure documents build successfully before committing to CVS.
How do you update the webserver (i.e. the pages on privoxy.org)?
First, build the docs by running make dok (or alternately make redhat-dok).
Run make webserver which copies all files from doc/webserver to the sourceforge webserver via scp.
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, or "elements", are definable in SGML. There is no set "standards". Since we are using Docbook, our tags are those that are defined by Docbook. 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 "closed". 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] XML.
Our documents use "sections" for the most part. Sections will be processed into HTML headers (e.g. h1 for sect1). The Docbook stylesheets will use these to also generate the Table of Contents for each doc. Our TOC's are set to a depth of three. Meaning sect1, sect2, and sect3 will have TOC entries, but sect4 will not. Each section requires a <title> element, and at least one <para>. There is a limit of five section levels in Docbook, but generally three should be sufficient for our purposes.
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. |
<filename></filename>, files and directories. |
<command></command>, command examples. |
<literallayout></literllayout>, like <pre>, more or less. |
<itemizedlist></itemizdelist>, 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.
It will be easier if everyone follows a similar writing style. This just makes it easier to read what someone else has written if it is all done in a similar fashion.
Here it is:
All tags should be lower case.
Tags delimiting a block of text should be on their own line. Like:
<para>
Some text goes here.
</para>
Just to <emphasis>emphasize</emphasis>, some text goes here.
Tags should be nested and step indented like:
<para>
<itemizedlist>
<para>
<listitem>
Some text goes here in our list example.
</listitem>
</para>
</itemizedlist>
</para>
Use white space to separate logical divisions within a document, like between sections. Running everything together consistently makes it harder to read and work on.
Do not hesitate to make comments. Comments can either use the <comment> element, or the <!-- --> style comment familiar from HTML.
We have an international audience. Refrain from slang, or English idiosyncrasies (too many to list :).
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 instance.
Our documents are available in differing formats. Right now, they are just plain text, and HTML, but PDF, and others is always a future possibility. Be careful with URLs (<ulink>), and avoid this mistake:
My favorite site is <ulink url="http://example.com">here</ulink>.
This will render as "My favorite site is here", which is not real helpful in a text doc. Better like this:
My favorite site is <ulink url="http://example.com">example.com</ulink>.
All documents should be spell checked occasionally. aspell can check SGML with the -H option. (ispell I think too.)
Privoxy documentation is using a number of customized "entities" to facilitate documentation maintenance.
We are using a set of "boilerplate" files with generic text, that is used by multiple docs. This way we can write something once, and use it repeatedly without having to re-write the same content over and over again. If editing such a file, keep in mind that it should be generic. That is the purpose; so it can be used in varying contexts without additional modifications.
We are also using what Docbook calls "internal entities". These are like variables in programming. Well, sort of. For instance, we have the p-version entity that contains the current 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.
Re-cyclable "boilerplate" text entities are defined like:
<!entity supported SYSTEM "supported.sgml">
In this example, the contents of the file, supported.sgml is available for inclusion anywhere in the doc. To make this happen, just reference the now defined entity: &supported; (starts with an ampersand and ends with a semi-colon), and the contents will be dumped into the finished doc at that point.
Commonly used "internal entities":
p-version: the Privoxy version string, e.g. "2.9.13". |
p-status: the project status, either "ALPHA", "BETA", or "STABLE". |
p-not-stable: use to conditionally include text in "not stable" releases (e.g. "BETA"). |
p-stable: just the opposite. |
p-text: this doc is only generated as text. |
There are others in various places that are defined for a specific purpose. Read the source!