| - Privoxy Developer Manual - | -||
|---|---|---|
| - Prev - | -- | -- Next - | -
| <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.
- 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 doc/webserver/*. And PDF version are kept in - doc/pdf/*. -
-- 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/. -
-- 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)? -
-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:
+- First, build the docs by running make dok (or alternately make redhat-dok). For PDF docs, do make dok-pdf. -
+All tags should be lower case.
- Run make webserver which - copies all files from doc/webserver to the sourceforge - webserver via scp. -
+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.
- 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). -
-- 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>
-
-
- 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>
-
-
- 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, HTML, and PDF, 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.18". - | -
| - 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. - | -
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.
-
- There are others in various places that are defined for a specific - purpose. Read the source! -
-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.)
+| - Prev - | -- Home - | -- Next - | -
| - The CVS Repository - | -- - | -- Coding Guidelines - | -
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!