| Privoxy Developer Manual | ||||
|---|---|---|---|---|
| Prev | - +Prev | - - | Next | +Next |
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.1 (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. 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 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 3. Documentation Guidelines +
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.1 (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. 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 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 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 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.
- +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.
+First, build the docs by running make dok.
Run make webserver which - copies all files from doc/webserver to the sourceforge webserver - via scp.
+Run make webserver which copies all files from doc/webserver to the sourceforge webserver via scp.
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 - 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).
- +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] 3.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 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. 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: 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. 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.
-
-
-
-
<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
+ <emphasis></emphasis>, the
stylesheets make this italics.
-
-
<filename></filename>, files
- and directories.
+ <filename></filename>, files and
+ directories.
-
-
<command></command>, command
+ <command></command>, command
examples.
-
-
<literallayout></literallayout>,
- like <pre>, more or less.
+ <literallayout></literallayout>, like
+ <pre>, more or less.
-
-
<itemizedlist></itemizedlist>,
- list with bullets.
+ <itemizedlist></itemizedlist>, list
+ with bullets.
-
-
<listitem></listitem>, member
- of the above.
+ <listitem></listitem>, member of the
+ above.
-
-
<screen></screen>, screen
- output, implies <literallayout>.
+ <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.
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.
- +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:
- +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)
- +Tags should be nested and step indented for block text like: (except in-line tags)
<para>
<itemizedlist>
<para>
@@ -276,173 +174,106 @@
</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.
+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>.)
+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.
+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.
+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>.
+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.)
+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.
- +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.
+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":
- +Commonly used "internal entities":
| p-version: the Privoxy version string, e.g. - "3.0.26". | +p-version: the Privoxy version string, e.g. "3.0.29". |
| 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 + | 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!
+There are others in various places that are defined for a specific purpose. Read the source!