2012-06-28 03:42:39 +00:00
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
|
|
|
|
|
<HTML
|
|
|
|
|
><HEAD
|
|
|
|
|
><TITLE
|
|
|
|
|
>Documentation Guidelines</TITLE
|
|
|
|
|
><META
|
|
|
|
|
NAME="GENERATOR"
|
|
|
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
|
|
|
|
|
REL="HOME"
|
|
|
|
|
TITLE="Privoxy Developer Manual"
|
|
|
|
|
HREF="index.html"><LINK
|
|
|
|
|
REL="PREVIOUS"
|
|
|
|
|
TITLE="The CVS Repository"
|
|
|
|
|
HREF="cvs.html"><LINK
|
|
|
|
|
REL="NEXT"
|
|
|
|
|
TITLE="Coding Guidelines"
|
|
|
|
|
HREF="coding.html"><LINK
|
|
|
|
|
REL="STYLESHEET"
|
|
|
|
|
TYPE="text/css"
|
|
|
|
|
HREF="../p_doc.css"><META
|
|
|
|
|
HTTP-EQUIV="Content-Type"
|
|
|
|
|
CONTENT="text/html;
|
|
|
|
|
charset=ISO-8859-1"></HEAD
|
|
|
|
|
><BODY
|
|
|
|
|
CLASS="SECT1"
|
|
|
|
|
BGCOLOR="#EEEEEE"
|
|
|
|
|
TEXT="#000000"
|
|
|
|
|
LINK="#0000FF"
|
|
|
|
|
VLINK="#840084"
|
|
|
|
|
ALINK="#0000FF"
|
|
|
|
|
><DIV
|
|
|
|
|
CLASS="NAVHEADER"
|
|
|
|
|
><TABLE
|
|
|
|
|
SUMMARY="Header navigation table"
|
|
|
|
|
WIDTH="100%"
|
|
|
|
|
BORDER="0"
|
|
|
|
|
CELLPADDING="0"
|
|
|
|
|
CELLSPACING="0"
|
|
|
|
|
><TR
|
|
|
|
|
><TH
|
|
|
|
|
COLSPAN="3"
|
|
|
|
|
ALIGN="center"
|
|
|
|
|
>Privoxy Developer Manual</TH
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
WIDTH="10%"
|
|
|
|
|
ALIGN="left"
|
|
|
|
|
VALIGN="bottom"
|
|
|
|
|
><A
|
|
|
|
|
HREF="cvs.html"
|
|
|
|
|
ACCESSKEY="P"
|
|
|
|
|
>Prev</A
|
|
|
|
|
></TD
|
|
|
|
|
><TD
|
|
|
|
|
WIDTH="80%"
|
|
|
|
|
ALIGN="center"
|
|
|
|
|
VALIGN="bottom"
|
|
|
|
|
></TD
|
|
|
|
|
><TD
|
|
|
|
|
WIDTH="10%"
|
|
|
|
|
ALIGN="right"
|
|
|
|
|
VALIGN="bottom"
|
|
|
|
|
><A
|
|
|
|
|
HREF="coding.html"
|
|
|
|
|
ACCESSKEY="N"
|
|
|
|
|
>Next</A
|
|
|
|
|
></TD
|
|
|
|
|
></TR
|
|
|
|
|
></TABLE
|
|
|
|
|
><HR
|
|
|
|
|
ALIGN="LEFT"
|
|
|
|
|
WIDTH="100%"></DIV
|
|
|
|
|
><DIV
|
|
|
|
|
CLASS="SECT1"
|
|
|
|
|
><H1
|
|
|
|
|
CLASS="SECT1"
|
|
|
|
|
><A
|
|
|
|
|
NAME="DOCUMENTATION"
|
|
|
|
|
>3. Documentation Guidelines</A
|
|
|
|
|
></H1
|
|
|
|
|
><P
|
|
|
|
|
> All formal documents are maintained in Docbook SGML and located in the
|
|
|
|
|
<SAMP
|
|
|
|
|
CLASS="COMPUTEROUTPUT"
|
|
|
|
|
>doc/source/*</SAMP
|
|
|
|
|
> directory. You will need
|
|
|
|
|
<A
|
|
|
|
|
HREF="http://www.docbook.org"
|
|
|
|
|
TARGET="_top"
|
|
|
|
|
>Docbook</A
|
|
|
|
|
>, the Docbook
|
2012-05-03 18:32:18 +00:00
|
|
|
DTD's and the Docbook modular stylesheets (or comparable alternatives),
|
2012-06-28 03:42:39 +00:00
|
|
|
and either <SPAN
|
|
|
|
|
CLASS="APPLICATION"
|
|
|
|
|
>jade</SPAN
|
|
|
|
|
> or
|
|
|
|
|
<SPAN
|
|
|
|
|
CLASS="APPLICATION"
|
|
|
|
|
>openjade</SPAN
|
|
|
|
|
> (recommended) installed in order to
|
|
|
|
|
build docs from source. Currently there is <A
|
|
|
|
|
HREF="../user-manual/index.html"
|
|
|
|
|
TARGET="_top"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="CITETITLE"
|
|
|
|
|
>user-manual</I
|
|
|
|
|
></A
|
|
|
|
|
>,
|
|
|
|
|
<A
|
|
|
|
|
HREF="../faq/index.html"
|
|
|
|
|
TARGET="_top"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="CITETITLE"
|
|
|
|
|
>FAQ</I
|
|
|
|
|
></A
|
|
|
|
|
>, and, of
|
|
|
|
|
course this, the <I
|
|
|
|
|
CLASS="CITETITLE"
|
|
|
|
|
>developer-manual</I
|
|
|
|
|
> in this format.
|
|
|
|
|
The <I
|
|
|
|
|
CLASS="CITETITLE"
|
|
|
|
|
>README</I
|
|
|
|
|
>, <I
|
|
|
|
|
CLASS="CITETITLE"
|
|
|
|
|
>AUTHORS</I
|
|
|
|
|
>,
|
|
|
|
|
<I
|
|
|
|
|
CLASS="CITETITLE"
|
|
|
|
|
>INSTALL</I
|
|
|
|
|
>,
|
|
|
|
|
<I
|
|
|
|
|
CLASS="CITETITLE"
|
|
|
|
|
>privoxy.1</I
|
|
|
|
|
> (man page), and
|
|
|
|
|
<I
|
|
|
|
|
CLASS="CITETITLE"
|
|
|
|
|
>config</I
|
|
|
|
|
> files are also now maintained as Docbook
|
|
|
|
|
SGML. These files, when built, in the top-level source directory are
|
|
|
|
|
generated files! Also, the <SPAN
|
|
|
|
|
CLASS="APPLICATION"
|
|
|
|
|
>Privoxy</SPAN
|
|
|
|
|
> <TT
|
|
|
|
|
CLASS="FILENAME"
|
|
|
|
|
>index.html</TT
|
|
|
|
|
> (and a
|
|
|
|
|
variation on this file, <TT
|
|
|
|
|
CLASS="FILENAME"
|
|
|
|
|
>privoxy-index.html</TT
|
|
|
|
|
>,
|
|
|
|
|
meant for inclusion with doc packages), are maintained as SGML as well.
|
|
|
|
|
<SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
>DO NOT edit these directly</I
|
|
|
|
|
></SPAN
|
|
|
|
|
>. Edit the SGML source, or
|
|
|
|
|
contact someone involved in the documentation.
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> <TT
|
|
|
|
|
CLASS="FILENAME"
|
|
|
|
|
>config</TT
|
|
|
|
|
> requires some special handling. The reason it
|
|
|
|
|
is maintained this way is so that the extensive comments in the file
|
|
|
|
|
mirror those in <I
|
|
|
|
|
CLASS="CITETITLE"
|
|
|
|
|
>user-manual</I
|
|
|
|
|
>. 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 <TT
|
|
|
|
|
CLASS="FILENAME"
|
|
|
|
|
>config.new</TT
|
|
|
|
|
>,
|
|
|
|
|
which should be reviewed for errors and mis-formatting. Once satisfied
|
|
|
|
|
that it is correct, then it should be hand copied to
|
|
|
|
|
<TT
|
|
|
|
|
CLASS="FILENAME"
|
|
|
|
|
>config</TT
|
|
|
|
|
>.
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> Other, less formal documents (e.g. <TT
|
|
|
|
|
CLASS="FILENAME"
|
|
|
|
|
>LICENSE</TT
|
|
|
|
|
>) are
|
|
|
|
|
maintained as plain text files in the top-level source directory.
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> 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
|
|
|
|
|
<TT
|
|
|
|
|
CLASS="FILENAME"
|
|
|
|
|
>doc/webserver/*</TT
|
|
|
|
|
>. And PDF version are kept in
|
|
|
|
|
<TT
|
|
|
|
|
CLASS="FILENAME"
|
|
|
|
|
>doc/pdf/*</TT
|
|
|
|
|
>.
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> Formal documents are built with the Makefile targets of
|
|
|
|
|
<SAMP
|
|
|
|
|
CLASS="COMPUTEROUTPUT"
|
|
|
|
|
>make dok</SAMP
|
|
|
|
|
>, or alternately
|
|
|
|
|
<SAMP
|
|
|
|
|
CLASS="COMPUTEROUTPUT"
|
|
|
|
|
>make redhat-dok</SAMP
|
|
|
|
|
>. If you have problems,
|
|
|
|
|
try both. The build process uses the document SGML sources in
|
|
|
|
|
<SAMP
|
|
|
|
|
CLASS="COMPUTEROUTPUT"
|
|
|
|
|
>doc/source/*/*</SAMP
|
|
|
|
|
> to update all text files in
|
|
|
|
|
<SAMP
|
|
|
|
|
CLASS="COMPUTEROUTPUT"
|
|
|
|
|
>doc/text/</SAMP
|
|
|
|
|
> and to update all HTML
|
|
|
|
|
documents in <SAMP
|
|
|
|
|
CLASS="COMPUTEROUTPUT"
|
|
|
|
|
>doc/webserver/</SAMP
|
|
|
|
|
>.
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> Documentation writers should please make sure documents build
|
|
|
|
|
successfully before committing to CVS, if possible.
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> How do you update the webserver (i.e. the pages on privoxy.org)?
|
|
|
|
|
|
|
|
|
|
<P
|
|
|
|
|
></P
|
|
|
|
|
><OL
|
|
|
|
|
TYPE="1"
|
|
|
|
|
><LI
|
|
|
|
|
><P
|
|
|
|
|
> First, build the docs by running <SAMP
|
|
|
|
|
CLASS="COMPUTEROUTPUT"
|
|
|
|
|
>make
|
|
|
|
|
dok</SAMP
|
|
|
|
|
> (or alternately <SAMP
|
|
|
|
|
CLASS="COMPUTEROUTPUT"
|
|
|
|
|
>make
|
|
|
|
|
redhat-dok</SAMP
|
|
|
|
|
>). For PDF docs, do <SAMP
|
|
|
|
|
CLASS="COMPUTEROUTPUT"
|
|
|
|
|
>make
|
|
|
|
|
dok-pdf</SAMP
|
|
|
|
|
>.
|
|
|
|
|
</P
|
|
|
|
|
></LI
|
|
|
|
|
><LI
|
|
|
|
|
><P
|
|
|
|
|
> Run <SAMP
|
|
|
|
|
CLASS="COMPUTEROUTPUT"
|
|
|
|
|
>make webserver</SAMP
|
|
|
|
|
> which copies all
|
|
|
|
|
files from <SAMP
|
|
|
|
|
CLASS="COMPUTEROUTPUT"
|
|
|
|
|
>doc/webserver</SAMP
|
|
|
|
|
> to the
|
|
|
|
|
sourceforge webserver via scp.
|
|
|
|
|
</P
|
|
|
|
|
></LI
|
|
|
|
|
></OL
|
|
|
|
|
>
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> Finished docs should be occasionally submitted to CVS
|
|
|
|
|
(<TT
|
|
|
|
|
CLASS="FILENAME"
|
|
|
|
|
>doc/webserver/*/*.html</TT
|
|
|
|
|
>) 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 <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
>after</I
|
|
|
|
|
></SPAN
|
|
|
|
|
> the <TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
>$VERSION</TT
|
|
|
|
|
> and
|
|
|
|
|
other release specific data in <TT
|
|
|
|
|
CLASS="FILENAME"
|
|
|
|
|
>configure.in</TT
|
|
|
|
|
> has been
|
|
|
|
|
updated (this is done just prior to a new release).
|
|
|
|
|
</P
|
|
|
|
|
><DIV
|
|
|
|
|
CLASS="SECT2"
|
|
|
|
|
><H2
|
|
|
|
|
CLASS="SECT2"
|
|
|
|
|
><A
|
|
|
|
|
NAME="SGML"
|
|
|
|
|
>3.1. Quickstart to Docbook and SGML</A
|
|
|
|
|
></H2
|
|
|
|
|
><P
|
|
|
|
|
> 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
|
|
|
|
|
<SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"tags"</SPAN
|
|
|
|
|
> 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 <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"elements"</SPAN
|
|
|
|
|
>, are definable in SGML. There is no set
|
|
|
|
|
<SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"standards"</SPAN
|
|
|
|
|
>. Since we are using
|
|
|
|
|
<SPAN
|
|
|
|
|
CLASS="APPLICATION"
|
|
|
|
|
>Docbook</SPAN
|
|
|
|
|
>, our tags are those that are defined by
|
|
|
|
|
<SPAN
|
|
|
|
|
CLASS="APPLICATION"
|
|
|
|
|
>Docbook</SPAN
|
|
|
|
|
>. Much of how the finish document is
|
|
|
|
|
rendered is determined by the <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"stylesheets"</SPAN
|
|
|
|
|
>.
|
|
|
|
|
The stylesheets determine how each tag gets translated to HTML, or other
|
|
|
|
|
formats.</P
|
|
|
|
|
><P
|
|
|
|
|
> Tags in Docbook SGML need to be always <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"closed"</SPAN
|
|
|
|
|
>. If not, you
|
|
|
|
|
will likely generate errors. Example: <TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
><title>My
|
|
|
|
|
Title</title></TT
|
|
|
|
|
>. They are also case-insensitive, but we
|
|
|
|
|
strongly suggest using all lower case. This keeps compatibility with
|
|
|
|
|
[Docbook] <SPAN
|
|
|
|
|
CLASS="APPLICATION"
|
|
|
|
|
>XML</SPAN
|
|
|
|
|
>.</P
|
|
|
|
|
><P
|
|
|
|
|
> Our documents use <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"sections"</SPAN
|
|
|
|
|
> for the most part. Sections
|
|
|
|
|
will be processed into HTML headers (e.g. <TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
>h1</TT
|
|
|
|
|
> for
|
|
|
|
|
<TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
>sect1</TT
|
|
|
|
|
>). The <SPAN
|
|
|
|
|
CLASS="APPLICATION"
|
|
|
|
|
>Docbook</SPAN
|
|
|
|
|
> 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 <TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
>sect1</TT
|
|
|
|
|
>,
|
|
|
|
|
<TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
>sect2</TT
|
|
|
|
|
>, and <TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
>sect3</TT
|
|
|
|
|
> will have TOC
|
|
|
|
|
entries, but <TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
>sect4</TT
|
|
|
|
|
> will not. Each section requires
|
|
|
|
|
a <TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
><title></TT
|
|
|
|
|
> element, and at least one
|
|
|
|
|
<TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
><para></TT
|
|
|
|
|
>. There is a limit of five section
|
|
|
|
|
levels in Docbook, but generally three should be sufficient for our
|
|
|
|
|
purposes.</P
|
|
|
|
|
><P
|
|
|
|
|
> Some common elements that you likely will use: </P
|
|
|
|
|
><P
|
|
|
|
|
> <P
|
|
|
|
|
></P
|
|
|
|
|
><TABLE
|
|
|
|
|
BORDER="0"
|
|
|
|
|
><TBODY
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
><para></para></I
|
|
|
|
|
></SPAN
|
|
|
|
|
>, paragraph delimiter. Most
|
|
|
|
|
text needs to be within paragraph elements (there are some exceptions).
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
><emphasis></emphasis></I
|
|
|
|
|
></SPAN
|
|
|
|
|
>, the stylesheets
|
|
|
|
|
make this italics.
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
><filename></filename></I
|
|
|
|
|
></SPAN
|
|
|
|
|
>, files and directories.
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
><command></command></I
|
|
|
|
|
></SPAN
|
|
|
|
|
>, command examples.
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
><literallayout></literallayout></I
|
|
|
|
|
></SPAN
|
|
|
|
|
>, like
|
|
|
|
|
<TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
><pre></TT
|
|
|
|
|
>, more or less.
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
><itemizedlist></itemizedlist></I
|
|
|
|
|
></SPAN
|
|
|
|
|
>, list with bullets.
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
><listitem></listitem></I
|
|
|
|
|
></SPAN
|
|
|
|
|
>, member of the above.
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
><screen></screen></I
|
|
|
|
|
></SPAN
|
|
|
|
|
>, screen output, implies
|
|
|
|
|
<TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
><literallayout></TT
|
|
|
|
|
>.
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
><ulink url="example.com"></ulink></I
|
|
|
|
|
></SPAN
|
|
|
|
|
>, like
|
|
|
|
|
HTML <TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
><a></TT
|
|
|
|
|
> tag.
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
><quote></quote></I
|
|
|
|
|
></SPAN
|
|
|
|
|
>, for, doh, quoting text.
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
></TBODY
|
|
|
|
|
></TABLE
|
|
|
|
|
><P
|
|
|
|
|
></P
|
|
|
|
|
></P
|
|
|
|
|
><P
|
|
|
|
|
> Look at any of the existing docs for examples of all these and more.</P
|
|
|
|
|
><P
|
|
|
|
|
> You might also find <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"<A
|
|
|
|
|
HREF="http://opensource.bureau-cornavin.com/crash-course/index.html"
|
|
|
|
|
TARGET="_top"
|
|
|
|
|
>Writing Documentation
|
|
|
|
|
Using DocBook - A Crash Course</A
|
|
|
|
|
>"</SPAN
|
|
|
|
|
> useful.</P
|
|
|
|
|
></DIV
|
|
|
|
|
><DIV
|
|
|
|
|
CLASS="SECT2"
|
|
|
|
|
><H2
|
|
|
|
|
CLASS="SECT2"
|
|
|
|
|
><A
|
|
|
|
|
NAME="DOCSTYLE"
|
|
|
|
|
>3.2. <SPAN
|
|
|
|
|
CLASS="APPLICATION"
|
|
|
|
|
>Privoxy</SPAN
|
|
|
|
|
> Documentation Style</A
|
|
|
|
|
></H2
|
|
|
|
|
><P
|
|
|
|
|
> 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.
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> Here it is:
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> <P
|
|
|
|
|
></P
|
|
|
|
|
><UL
|
|
|
|
|
><LI
|
|
|
|
|
><P
|
|
|
|
|
> All tags should be lower case.
|
|
|
|
|
</P
|
|
|
|
|
></LI
|
|
|
|
|
><LI
|
|
|
|
|
><P
|
|
|
|
|
> Tags delimiting a <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
>block</I
|
|
|
|
|
></SPAN
|
|
|
|
|
> of text (even small
|
|
|
|
|
blocks) should be on their own line. Like:
|
|
|
|
|
<P
|
|
|
|
|
CLASS="LITERALLAYOUT"
|
|
|
|
|
> <para><br>
|
|
|
|
|
Some text goes here.<br>
|
|
|
|
|
</para><br>
|
|
|
|
|
</P
|
|
|
|
|
>
|
|
|
|
|
Tags marking individual words, or few words, should be in-line:
|
|
|
|
|
<P
|
|
|
|
|
CLASS="LITERALLAYOUT"
|
|
|
|
|
> Just to <emphasis>emphasize</emphasis>, some text goes here.<br>
|
|
|
|
|
</P
|
|
|
|
|
>
|
|
|
|
|
</P
|
|
|
|
|
></LI
|
|
|
|
|
><LI
|
|
|
|
|
><P
|
|
|
|
|
> Tags should be nested and step indented for block text like: (except
|
|
|
|
|
in-line tags)
|
|
|
|
|
<P
|
|
|
|
|
CLASS="LITERALLAYOUT"
|
|
|
|
|
> <para><br>
|
|
|
|
|
<itemizedlist><br>
|
|
|
|
|
<para><br>
|
|
|
|
|
<listitem><br>
|
|
|
|
|
Some text goes here in our list example.<br>
|
|
|
|
|
</listitem><br>
|
|
|
|
|
</para><br>
|
|
|
|
|
</itemizedlist><br>
|
|
|
|
|
</para><br>
|
|
|
|
|
</P
|
|
|
|
|
>
|
|
|
|
|
This makes it easier to find the text amongst the tags ;-)
|
|
|
|
|
</P
|
|
|
|
|
></LI
|
|
|
|
|
><LI
|
|
|
|
|
><P
|
|
|
|
|
> 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.
|
|
|
|
|
</P
|
|
|
|
|
></LI
|
|
|
|
|
><LI
|
|
|
|
|
><P
|
|
|
|
|
> 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>.)
|
|
|
|
|
</P
|
|
|
|
|
></LI
|
|
|
|
|
><LI
|
|
|
|
|
><P
|
|
|
|
|
> We have an international audience. Refrain from slang, or English
|
|
|
|
|
idiosyncrasies (too many to list :). Humor also does not translate
|
|
|
|
|
well sometimes.
|
|
|
|
|
</P
|
|
|
|
|
></LI
|
|
|
|
|
><LI
|
|
|
|
|
><P
|
|
|
|
|
> 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.
|
|
|
|
|
</P
|
|
|
|
|
></LI
|
|
|
|
|
><LI
|
|
|
|
|
><P
|
|
|
|
|
> 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:
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> My favorite site is <ulink url="http://example.com">here</ulink>.
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> This will render as <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"My favorite site is here"</SPAN
|
|
|
|
|
>, which is
|
|
|
|
|
not real helpful in a text doc. Better like this:
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> My favorite site is <ulink url="http://example.com">example.com</ulink>.
|
|
|
|
|
</P
|
|
|
|
|
></LI
|
|
|
|
|
><LI
|
|
|
|
|
><P
|
|
|
|
|
> All documents should be spell checked occasionally.
|
|
|
|
|
<SPAN
|
|
|
|
|
CLASS="APPLICATION"
|
|
|
|
|
>aspell</SPAN
|
|
|
|
|
> can check SGML with the
|
|
|
|
|
<TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
>-H</TT
|
|
|
|
|
> option. (<SPAN
|
|
|
|
|
CLASS="APPLICATION"
|
|
|
|
|
>ispell</SPAN
|
|
|
|
|
> I think
|
|
|
|
|
too.)
|
|
|
|
|
</P
|
|
|
|
|
></LI
|
|
|
|
|
></UL
|
|
|
|
|
>
|
|
|
|
|
</P
|
|
|
|
|
></DIV
|
|
|
|
|
><DIV
|
|
|
|
|
CLASS="SECT2"
|
|
|
|
|
><H2
|
|
|
|
|
CLASS="SECT2"
|
|
|
|
|
><A
|
|
|
|
|
NAME="AEN217"
|
|
|
|
|
>3.3. Privoxy Custom Entities</A
|
|
|
|
|
></H2
|
|
|
|
|
><P
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="APPLICATION"
|
|
|
|
|
>Privoxy</SPAN
|
|
|
|
|
> documentation is using
|
|
|
|
|
a number of customized <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"entities"</SPAN
|
|
|
|
|
> to facilitate
|
|
|
|
|
documentation maintenance.
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> We are using a set of <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"boilerplate"</SPAN
|
|
|
|
|
> 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
|
|
|
|
|
<SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
>generic</I
|
|
|
|
|
></SPAN
|
|
|
|
|
>. That is the purpose; so it can be used in varying
|
|
|
|
|
contexts without additional modifications.
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> We are also using what <SPAN
|
|
|
|
|
CLASS="APPLICATION"
|
|
|
|
|
>Docbook</SPAN
|
|
|
|
|
> calls
|
|
|
|
|
<SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"internal entities"</SPAN
|
|
|
|
|
>. These are like variables in
|
|
|
|
|
programming. Well, sort of. For instance, we have the
|
|
|
|
|
<TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
>p-version</TT
|
|
|
|
|
> entity that contains the current
|
|
|
|
|
<SPAN
|
|
|
|
|
CLASS="APPLICATION"
|
|
|
|
|
>Privoxy</SPAN
|
|
|
|
|
> 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.
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> <P
|
|
|
|
|
></P
|
|
|
|
|
><UL
|
|
|
|
|
><LI
|
|
|
|
|
><P
|
|
|
|
|
> Re- <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"boilerplate"</SPAN
|
|
|
|
|
> text entities are defined like:
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> <TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
><!entity supported SYSTEM "supported.sgml"></TT
|
|
|
|
|
>
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> In this example, the contents of the file,
|
|
|
|
|
<TT
|
|
|
|
|
CLASS="FILENAME"
|
|
|
|
|
>supported.sgml</TT
|
|
|
|
|
> is available for inclusion anywhere
|
|
|
|
|
in the doc. To make this happen, just reference the now defined
|
|
|
|
|
entity: <TT
|
|
|
|
|
CLASS="LITERAL"
|
|
|
|
|
>&supported;</TT
|
|
|
|
|
> (starts with an ampersand
|
|
|
|
|
and ends with a semi-colon), and the contents will be dumped into
|
|
|
|
|
the finished doc at that point.
|
|
|
|
|
</P
|
|
|
|
|
></LI
|
|
|
|
|
><LI
|
|
|
|
|
><P
|
|
|
|
|
> Commonly used <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"internal entities"</SPAN
|
|
|
|
|
>:
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
></P
|
|
|
|
|
><TABLE
|
|
|
|
|
BORDER="0"
|
|
|
|
|
><TBODY
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
>p-version</I
|
|
|
|
|
></SPAN
|
|
|
|
|
>: the <SPAN
|
|
|
|
|
CLASS="APPLICATION"
|
|
|
|
|
>Privoxy</SPAN
|
|
|
|
|
>
|
|
|
|
|
version string, e.g. <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"3.0.12"</SPAN
|
|
|
|
|
>.
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
>p-status</I
|
|
|
|
|
></SPAN
|
|
|
|
|
>: the project status, either
|
|
|
|
|
<SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"alpha"</SPAN
|
|
|
|
|
>, <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"beta"</SPAN
|
|
|
|
|
>, or <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"stable"</SPAN
|
|
|
|
|
>.
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
>p-not-stable</I
|
|
|
|
|
></SPAN
|
|
|
|
|
>: use to conditionally include
|
|
|
|
|
text in <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"not stable"</SPAN
|
|
|
|
|
> releases (e.g. <SPAN
|
|
|
|
|
CLASS="QUOTE"
|
|
|
|
|
>"beta"</SPAN
|
|
|
|
|
>).
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
>p-stable</I
|
|
|
|
|
></SPAN
|
|
|
|
|
>: just the opposite.
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
> <SPAN
|
|
|
|
|
CLASS="emphasis"
|
|
|
|
|
><I
|
|
|
|
|
CLASS="EMPHASIS"
|
|
|
|
|
>p-text</I
|
|
|
|
|
></SPAN
|
|
|
|
|
>: this doc is only generated as text.
|
|
|
|
|
</TD
|
|
|
|
|
></TR
|
|
|
|
|
></TBODY
|
|
|
|
|
></TABLE
|
|
|
|
|
><P
|
|
|
|
|
></P
|
|
|
|
|
></LI
|
|
|
|
|
></UL
|
|
|
|
|
>
|
|
|
|
|
</P
|
|
|
|
|
><P
|
|
|
|
|
> There are others in various places that are defined for a specific
|
|
|
|
|
purpose. Read the source!
|
|
|
|
|
</P
|
|
|
|
|
></DIV
|
|
|
|
|
></DIV
|
|
|
|
|
><DIV
|
|
|
|
|
CLASS="NAVFOOTER"
|
|
|
|
|
><HR
|
|
|
|
|
ALIGN="LEFT"
|
|
|
|
|
WIDTH="100%"><TABLE
|
|
|
|
|
SUMMARY="Footer navigation table"
|
|
|
|
|
WIDTH="100%"
|
|
|
|
|
BORDER="0"
|
|
|
|
|
CELLPADDING="0"
|
|
|
|
|
CELLSPACING="0"
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
WIDTH="33%"
|
|
|
|
|
ALIGN="left"
|
|
|
|
|
VALIGN="top"
|
|
|
|
|
><A
|
|
|
|
|
HREF="cvs.html"
|
|
|
|
|
ACCESSKEY="P"
|
|
|
|
|
>Prev</A
|
|
|
|
|
></TD
|
|
|
|
|
><TD
|
|
|
|
|
WIDTH="34%"
|
|
|
|
|
ALIGN="center"
|
|
|
|
|
VALIGN="top"
|
|
|
|
|
><A
|
|
|
|
|
HREF="index.html"
|
|
|
|
|
ACCESSKEY="H"
|
|
|
|
|
>Home</A
|
|
|
|
|
></TD
|
|
|
|
|
><TD
|
|
|
|
|
WIDTH="33%"
|
|
|
|
|
ALIGN="right"
|
|
|
|
|
VALIGN="top"
|
|
|
|
|
><A
|
|
|
|
|
HREF="coding.html"
|
|
|
|
|
ACCESSKEY="N"
|
|
|
|
|
>Next</A
|
|
|
|
|
></TD
|
|
|
|
|
></TR
|
|
|
|
|
><TR
|
|
|
|
|
><TD
|
|
|
|
|
WIDTH="33%"
|
|
|
|
|
ALIGN="left"
|
|
|
|
|
VALIGN="top"
|
|
|
|
|
>The CVS Repository</TD
|
|
|
|
|
><TD
|
|
|
|
|
WIDTH="34%"
|
|
|
|
|
ALIGN="center"
|
|
|
|
|
VALIGN="top"
|
|
|
|
|
> </TD
|
|
|
|
|
><TD
|
|
|
|
|
WIDTH="33%"
|
|
|
|
|
ALIGN="right"
|
|
|
|
|
VALIGN="top"
|
|
|
|
|
>Coding Guidelines</TD
|
|
|
|
|
></TR
|
|
|
|
|
></TABLE
|
|
|
|
|
></DIV
|
|
|
|
|
></BODY
|
|
|
|
|
></HTML
|
|
|
|
|
>
|
