All formal documents are maintained in Docbook SGML and located in the doc/source/* directory. You will need Docbook, the Docbook 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 format. The README, - AUTHORS, INSTALL, privoxy.8 (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 (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.
-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 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.
-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 Git. HTML versions are also being kept in Git 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 Git, if - possible.
-How do you update the webserver (i.e. the pages on privoxy.org)?
-First, build the docs by running make dok dok-tidy.
-Run make webserver which copies all files from doc/webserver to the sourceforge webserver via ssh.
-Finished docs should be occasionally submitted to Git (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. 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 - "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 "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 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 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 (there are some exceptions). | -
| <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, 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.
-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>
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>
- <para>
- <listitem>
- Some text goes here in our list example.
+
+
All formal documents are maintained in Docbook SGML and located in the + doc/source/* directory. You will need + Docbook, the Docbook + 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 format. + The README, AUTHORS, + INSTALL, + privoxy.8 (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 (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. +
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 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. +
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 + Git. HTML versions are also being kept in Git 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 Git, if possible. +
How do you update the webserver (i.e. the pages on privoxy.org)? +
First, build the docs by running make + dok dok-tidy. +
Run make webserver which copies all + files from doc/webserver to the + sourceforge webserver via ssh. +
Finished docs should be occasionally submitted to Git + (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. + 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 + "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 + "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 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 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 (there are some exceptions). + |
| <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, quoting text. + |
Look at any of the existing docs for examples of all these and more.
You might also find
- </listitem>
- </para>
- </itemizedlist>
- </para>
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 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 -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 (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 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. "3.0.34". | -
| 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!
-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>
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>
+ <para>
+ <listitem>
+ Some text goes here in our list example.
+ </listitem>
+ </para>
+ </itemizedlist>
+ </para>
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 + 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 + -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 (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 + 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. "3.0.34". + |
| 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! +