Documentation Guidelines

Prev 4. Documentation Guidelines3. Documentation Guidelines

All formal documents are maintained in Docbook SGML and located in the - doc/source/*doc/source/* directory. You will need Docbook, the Docbook +>, the Docbook DTD's and the Docbook modular stylesheets (or comparable alternatives), and either , AUTHORS +>, + INSTALL, 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, (man page), and + config files are also now maintained as Docbook + SGML. These files, when built, in the top-level source directory are + generated files! Also, the Privoxy index.html, the +> (and a + variation on this file, privoxy-index.html, + meant for inclusion with doc packages), are maintained as SGML as well. Privoxy home page, is maintained as SGML. - DO NOT edit these directly. Edit the SGML source, or - contact someone involved in the documentation (at present Stefan and - Hal). + contact someone involved in the documentation.

Other, less formal documents (e.g. LICENSEconfig requires some special handling. The reason it + is maintained this way is so that the extensive comments in the file + mirror those in user-manual. But the conversion + process requires going from SGML to HTML to text to special formatting + required for the embedded comments. Some of this does not survive so + well. Especially some of the examples that are longer than 80 characters. + The build process for this file outputs to config.new, + which should be reviewed for errors and mis-formatting. Once satisfied + that it is correct, then it should be hand copied to INSTALL) are maintained as plain text files in the - top-level source directory. At least for the time being. +>config. +

Other, less formal documents (e.g. LICENSE) are + maintained as plain text files in the top-level source directory.

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. HTML versions are also now being kept in CVS under + Git. HTML versions are also being kept in Git under doc/webserver/*

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 - make dok. + The build process uses the document SGML sources in + doc/source/*/*doc/source/*/* to update all text files in - doc/text/doc/text/ and to update all HTML - documents in doc/webserver/doc/webserver/.

Documentation writers should please make sure documents build - successfully before committing to CVS. + successfully before committing to Git, if possible.

How do you update the webserver (i.e. the pages on privoxy.org)? - -

First, build the docs by running make - dok (or alternately First, build the docs by running make - redhat-dok). + dok.
Run Run make webservermake webserver which copies all - files from doc/webserverdoc/webserver to the sourceforge webserver via scp.

-
Finished docs should be occasionally submitted to CVS +> Finished docs should be occasionally submitted to Git (doc/webserver/*/*.html) so that those without +>) 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 $VERSION4.1. Quickstart to Docbook and SGML3.1. Quickstart to Docbook and SGML
If you are not familiar with SGML, it is a markup language similar to HTML. - Actually, not a mark up language per se, but a language used to define +> If you are not familiar with SGML, it is a markup language similar to HTML. + Actually, not a mark up language per se, but a language used to define markup languages. In fact, HTML is an SGML application. Both will use Docbook, our tags are those that are defined by +>, our tags are those that are defined by Docbookh1 for +> for sect1Docbook stylesheets - will use these to also generate the Table of Contents for each doc. Our + 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 +> will have TOC entries, but sect4 will not. Each section requires +> will not. Each section requires a <title> element, and at least one +> element, and at least one <para>. There is a limit of five section - levels in Docbook, but generally three should be sufficient for our +>. 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:
Some common elements that you likely will use:

, paragraph delimiter. Most + text needs to be within paragraph elements (there are some exceptions). + , the stylesheets + make this italics. + , for, doh, quoting text. +

<para></para>, paragraph delimiter. Most - text needs to be within paragraph elements (there are some exceptions). -

<emphasis></emphasis>, the stylesheets make this - italics. -

<filename></filename>, files and directories. -

<command></command>, command examples. -

<literallayout></literallayout>, like - , like + <pre>, more or less. -

<itemizedlist></itemizedlist>, list with bullets. -

<listitem></listitem>, member of the above. -

<screen></screen>, screen output, implies - , screen output, implies + <literallayout>. -

<ulink url="example.com"></ulink>, like - HTML , 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.

4.2. 3.2. Privoxy Documentation Style
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 +> 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:

Tags delimiting a Tags delimiting a block of text (even small blocks) should be on their own line. Like: -
<para>
  Some text goes here.
</para>

- Tags marking individual words, or few words, should be in-line: -
Tags marking individual words, or few words, should be in-line: +
  Just to <emphasis>emphasize</emphasis>, some text goes here.

-
Tags should be nested and step indented for block text like: (except - in-line tags) -
<para>
  <itemizedlist>
@@ -515,29 +592,29 @@ CLASS="LITERALLAYOUT"   </itemizedlist>
</para>

- This makes it easier to find the text amongst the tags ;-) +>
This makes it easier to find the text amongst the tags ;-)
Use white space to separate logical divisions within a document, - like between sections. Running everything together consistently +> 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. (Note in Docbook v4.x <comment> is +> Do not hesitate to make comments. Comments can either use the + <comment> element, or the  style comment + 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 :). Humor also does not translate +> We have an international audience. Refrain from slang, or English + idiosyncrasies (too many to list :). Humor also does not translate well sometimes.
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 +> Our documents are available in differing formats. Right now, they + are just plain text and/or HTML, but others are always a + future possibility. Be careful with URLs (<ulink>), and avoid this mistake:
This will render as "My favorite site is here", which is +>, which is not real helpful in a text doc. Better like this:
-

4.3. Privoxy Custom Entities3.3. Privoxy Custom Entities

Privoxy documentation is using +> documentation is using a number of customized "entities" to facilitate - documentation maintenance. +> to facilitate + documentation maintenance.

We are using a set of generic. That is the purpose; so it can be used in varying +>. That is the purpose; so it can be used in varying contexts without additional modifications.

We are also using what Docbook calls +> calls "internal entities". These are like variables in +>. These are like variables in programming. Well, sort of. For instance, we have the p-version entity that contains the current +> entity that contains the current Privoxy version string. You are strongly - encouraged to use these where possible. Some of these obviously +> version string. You are strongly + encouraged to use these where possible. Some of these obviously 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.

supported.sgml is available for inclusion anywhere - in the doc. To make this happen, just reference the now defined +> 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 +> (starts with an ampersand + and ends with a semi-colon), and the contents will be dumped into the finished doc at that point.

p-version: the Privoxy +> version string, e.g. "2.9.14""3.0.27". p-status: the project status, either +>: the project status, either "alpha" p-not-stable: use to conditionally include +>: use to conditionally include text in "not stable" 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 +> There are others in various places that are defined for a specific purpose. Read the source!