X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fwebserver%2Fdeveloper-manual%2Fdocumentation.html;h=65d95584faa6d0329ac2a13127ad0357574ef7f4;hp=84989410898f73ca7c3c9a9fe82528ed81494a4c;hb=107c84d0c43b24ad437933c75774276f67165959;hpb=b18c9f379ff946b4ab307f555e1a0e1f5ad85dc8 diff --git a/doc/webserver/developer-manual/documentation.html b/doc/webserver/developer-manual/documentation.html index 84989410..65d95584 100644 --- a/doc/webserver/developer-manual/documentation.html +++ b/doc/webserver/developer-manual/documentation.html @@ -1,451 +1,520 @@ - - + - - Documentation Guidelines - - - - - - - - - - - -
-

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 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)?

- -
    -
  1. -

    First, build the docs by running make - dok.

    -
  2. - -
  3. -

    Run make webserver which - copies all files from doc/webserver to the sourceforge webserver - via scp.

    -
  4. -
- -

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).

- -
-

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.

- -

Some common elements that you likely will use:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + Documentation Guidelines + + + + + + + + + +
<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.
+ + + + + + + +
+ Privoxy Developer Manual +
+ Prev + + + Next +
- -

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.

+
- -
-

3.2. Privoxy Documentation Style

- -

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:

- - + + +

+ 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). +

+
+

+ 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. +

+

+ 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. +

+
+
+

+ 3.2. Privoxy + Documentation Style +

+

+ 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.) +

    +
  • +
+
+
+

+ 3.3. Privoxy Custom Entities +

+

+ 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.25". +
    + 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! +

+
- -
-

3.3. Privoxy Custom - Entities

- -

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.

- - - -

There are others in various places that are defined for a specific - purpose. Read the source!

+ -
- - - + +