All formal documents are maintained in Docbook SGML and located in the doc/source/* directory. You will need Docbook, the Docbook @@ -61,7 +54,6 @@ "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 file mirror those in user-manual. But the @@ -72,33 +64,26 @@ "FILENAME">config.new, which should be reviewed for errors and mis-formatting. Once satisfied that it is correct, then it should be hand copied to 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 being kept in CVS under doc/webserver/*.
-Formal documents are built with the Makefile targets of 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.
-How do you update the webserver (i.e. the pages on privoxy.org)?
-First, build the docs by running make dok.
Run make webserver which copies all files from
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 @@ -115,11 +99,9 @@ "LITERAL">$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. Actually, not a mark up language per se, but a language used to define markup languages. In fact, HTML is an SGML application. Both @@ -133,14 +115,12 @@ document is rendered is determined by the "stylesheets". The stylesheets determine how each tag gets translated to HTML, or other formats.
-Tags in Docbook 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 <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:
-| <emphasis></emphasis>, the stylesheets make this italics. |
| <filename></filename>, files and directories. |
| <command></command>, command examples. |
| <literallayout></literallayout>, like <pre>, more or less. |
| <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, @@ -221,52 +190,41 @@ |
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.
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 (even small blocks) 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 for block text like: (except in-line tags)
- <para>
<itemizedlist>
<para>
@@ -280,49 +238,40 @@
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 replaced by <remark>.)
We have an international audience. Refrain from slang, or English 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 lengthy URLs for instance.
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:
-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
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 @@ -347,7 +293,6 @@ 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 @@ -357,15 +302,12 @@ 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.
-Re- "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 @@ -373,20 +315,17 @@ 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. - "3.0.23". | + "3.0.27".
| p-status: the project status, either @@ -394,19 +333,16 @@ "QUOTE">"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 @@ -416,33 +352,25 @@ |
There are others in various places that are defined for a specific purpose. Read the source!