Documentation Guidelines

@@ -59,10 +45,10 @@ body { DTD's and the Docbook modular 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 + docs from source. Currently there is user-manual, FAQ, and, + of course this, the developer-manual in this format. The README, AUTHORS, INSTALL, privoxy.1 (man page), and config @@ -72,8 +58,9 @@ body { "FILENAME">index.html (and a variation on this file, privoxy-index.html, meant for inclusion with doc packages), are maintained as SGML as well. DO NOT edit these directly. Edit the SGML - source, or contact someone involved in the documentation.

+ "emphasis">DO NOT edit these directly. + Edit the SGML source, or contact someone involved in the + documentation.

config requires some special handling. The reason it is maintained this way is so that the extensive comments in the @@ -92,16 +79,14 @@ body {

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 being kept in CVS under doc/webserver/*. And PDF version are kept in doc/pdf/*.

+ "FILENAME">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 doc/source/*/* to update all text files in - doc/text/ and to update all HTML - documents in doc/webserver/.

+ "COMPUTEROUTPUT">make dok. 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, if possible.

@@ -111,9 +96,7 @@ body {

First, build the docs by running make - dok (or alternately make - redhat-dok). For PDF docs, do make dok-pdf.
+ dok.

@@ -128,9 +111,10 @@ body { "FILENAME">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).

+ "emphasis">after the $VERSION and other release specific data in configure.in has been updated (this is done just prior to + a new release).

3.1. Quickstart to Docbook @@ -175,65 +159,65 @@ body { - + - + - + - + - - - + - - + - +

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

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

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

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

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

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

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

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

<ulink - url="example.com"></ulink>, like HTML `<a>` tag. <ulink + url="example.com"></ulink>, like HTML + `<a>` tag.

<quote></quote>, for, - doh, quoting text. <quote></quote>, for, doh, + quoting text.

@@ -263,9 +247,9 @@ body {

Tags delimiting a block of text (even small blocks) - should be on their own line. Like:

Tags delimiting a block of text (even small blocks) should be + on their own line. Like:

<para>
Some text goes here.
@@ -324,7 +308,7 @@ body {

Our documents are available in differing formats. Right now, - they are just plain text, HTML, and PDF, but others are always a + they are just plain text and/or HTML, but others are always a future possibility. Be careful with URLs (<ulink>), and avoid this mistake:

@@ -349,7 +333,7 @@ body {

3.3. Privoxy Custom +
3.3. Privoxy Custom Entities

Privoxy documentation is using a @@ -360,9 +344,9 @@ body { 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.
+ 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 @@ -397,33 +381,36 @@ body { - + - - + - + - +

p-version: the - Privoxy version string, e.g. - "3.0.18". p-version: the Privoxy version string, e.g. + "3.0.20".

p-status: the - project status, either "alpha", - "beta", or 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-not-stable: use to conditionally + include text in "not stable" + releases (e.g. "beta").

p-stable: just - the opposite. p-stable: just the opposite.

p-text: this - doc is only generated as text. p-text: this doc is only generated as + text.

@@ -436,7 +423,7 @@ body {

<para></para>, - paragraph delimiter. Most text needs to be within paragraph - elements (there are some exceptions).	<para></para>, paragraph + delimiter. Most text needs to be within paragraph elements (there + are some exceptions).
<emphasis></emphasis>, - the stylesheets make this italics.	<emphasis></emphasis>, the + stylesheets make this italics.
<filename></filename>, - files and directories.	<filename></filename>, files + and directories.
<command></command>, - command examples.	<command></command>, command + examples.
<literallayout></literallayout>, +	<literallayout></literallayout>, like `<pre>`, more or less.
<itemizedlist></itemizedlist>, +	<itemizedlist></itemizedlist>, list with bullets.
<listitem></listitem>, - member of the above.	<listitem></listitem>, member + of the above.
<screen></screen>, - screen output, implies `<screen></screen>, screen + output, implies <literallayout>.`
<ulink - url="example.com"></ulink>, like HTML `<a>` tag.	<ulink + url="example.com"></ulink>, like HTML + `<a>` tag.
<quote></quote>, for, - doh, quoting text.	<quote></quote>, for, doh, + quoting text.

p-version: the - Privoxy version string, e.g. - "3.0.18".	p-version: the Privoxy version string, e.g. + "3.0.20".
p-status: the - project status, either "alpha", - "beta", or 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-not-stable: use to conditionally + include text in "not stable" + releases (e.g. "beta").
p-stable: just - the opposite.	p-stable: just the opposite.
p-text: this - doc is only generated as text.	p-text: this doc is only generated as + text.