+<!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.60"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
REL="PREVIOUS"
-TITLE="Quickstart to Privoxy Development"
-HREF="quickstart.html"><LINK
+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"></HEAD
+HREF="../p_doc.css"><META
+HTTP-EQUIV="Content-Type"
+CONTENT="text/html;
+charset=ISO-8859-1"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#EEEEEE"
><DIV
CLASS="NAVHEADER"
><TABLE
+SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
ALIGN="left"
VALIGN="bottom"
><A
-HREF="quickstart.html"
+HREF="cvs.html"
+ACCESSKEY="P"
>Prev</A
></TD
><TD
VALIGN="bottom"
><A
HREF="coding.html"
+ACCESSKEY="N"
>Next</A
></TD
></TR
CLASS="SECT1"
><A
NAME="DOCUMENTATION"
->4. Documentation Guidelines</A
+>3. Documentation Guidelines</A
></H1
><P
-> All formal documents are maintained in docbook SGML and located in the
- <TT
+> All formal documents are maintained in Docbook SGML and located in the
+ <SAMP
CLASS="COMPUTEROUTPUT"
->doc/source</TT
+>doc/source/*</SAMP
> directory. You will need
<A
HREF="http://www.docbook.org"
TARGET="_top"
->docbook</A
-> and the docbook
- stylesheets (or comparable alternatives), and either
- <SPAN
+>Docbook</A
+>, the Docbook
+ DTD's and the Docbook modular stylesheets (or comparable alternatives),
+ and either <SPAN
CLASS="APPLICATION"
>jade</SPAN
-> or <SPAN
+> or
+ <SPAN
CLASS="APPLICATION"
>openjade</SPAN
->
- (recommended) installed in order to build docs from source. Currently
- there is <A
+> (recommended) installed in order to
+ build docs from source. Currently there is <A
HREF="../user-manual/index.html"
TARGET="_top"
><I
CLASS="CITETITLE"
>FAQ</I
></A
->, and,
- of course this, the <I
+>, and, of
+ course this, the <I
CLASS="CITETITLE"
>developer-manual</I
-> in this
- format. The <I
+> in this format.
+ The <I
CLASS="CITETITLE"
>README</I
->, is also now maintained
- as SGML. The <I
+>, <I
CLASS="CITETITLE"
->README</I
-> in the top-level source
- directory is a generated file. <I
+>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 this
- directly</I
->. Edit the SGML source!
+>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. AUTHORS, LICENSE) are maintained as
- plain text files in the toplevel source directory. At least for the
- time being.
+> 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. Or HTML versions can be downloaded from the <A
-HREF="http://www.privoxy.org"
-TARGET="_top"
->www.privoxy.org</A
-> website, which
- should be fairly current. (This is only a temporary solution.)
+ 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
- <TT
+ <SAMP
CLASS="COMPUTEROUTPUT"
->make dok</TT
+>make dok</SAMP
>, or alternately
- <TT
+ <SAMP
CLASS="COMPUTEROUTPUT"
->make redhat-dok</TT
+>make redhat-dok</SAMP
>. If you have problems,
try both. The build process uses the document SGML sources in
- <TT
+ <SAMP
CLASS="COMPUTEROUTPUT"
->doc/source</TT
+>doc/source/*/*</SAMP
> to update all text files in
- <TT
+ <SAMP
CLASS="COMPUTEROUTPUT"
->doc/text</TT
+>doc/text/</SAMP
> and to update all HTML
- documents in <TT
+ documents in <SAMP
CLASS="COMPUTEROUTPUT"
->doc/webserver</TT
+>doc/webserver/</SAMP
>.
</P
><P
> Documentation writers should please make sure documents build
- successfully before committing to CVS.
+ successfully before committing to CVS, if possible.
</P
><P
> How do you update the webserver (i.e. the pages on privoxy.org)?
TYPE="1"
><LI
><P
-> First, build the docs by running <TT
+> First, build the docs by running <SAMP
+CLASS="COMPUTEROUTPUT"
+>make
+ dok</SAMP
+> (or alternately <SAMP
CLASS="COMPUTEROUTPUT"
>make
- dok</TT
-> (or alternately <TT
+ redhat-dok</SAMP
+>). For PDF docs, do <SAMP
CLASS="COMPUTEROUTPUT"
>make
- redhat-dok</TT
->).
+ dok-pdf</SAMP
+>.
</P
></LI
><LI
><P
-> Run <TT
+> Run <SAMP
CLASS="COMPUTEROUTPUT"
->make webserver</TT
+>make webserver</SAMP
> which copies all
- files from <TT
+ files from <SAMP
CLASS="COMPUTEROUTPUT"
->doc/webserver</TT
+>doc/webserver</SAMP
> to the
sourceforge webserver via scp.
</P
></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"
->4.1. Quickstart to Docbook and SGML</A
+>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.
- In fact, HTML is an SGML application. Both use <SPAN
+ 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 are much more varied,
- and flexible, but do much of the same kinds of things. The 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 <SPAN
CLASS="QUOTE"
>"elements"</SPAN
->, are definable in SGML. There is no
- set <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
+>, 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
+>. 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
+ The stylesheets determine how each tag gets translated to HTML, or other
+ formats.</P
><P
-> Tags in SGML need to be always <SPAN
+> Tags in Docbook SGML need to be always <SPAN
CLASS="QUOTE"
>"closed"</SPAN
->. If not, you
- will likely generate errors. Example:
- <TT
+>. 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
+><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
> Some common elements that you likely will use: </P
><P
+> <P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><para></para></I
+></SPAN
>, paragraph delimiter. Most
- text needs to be within paragraph elements.
- </TD
+ text needs to be within paragraph elements (there are some exceptions).
+ </TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><emphasis></emphasis></I
->, stylesheets make this
- italics.
- </TD
+></SPAN
+>, the stylesheets
+ make this italics.
+ </TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><filename></filename></I
+></SPAN
>, files and directories.
- </TD
+ </TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><command></command></I
+></SPAN
>, command examples.
- </TD
+ </TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
-><literallayout></literllayout></I
+><literallayout></literallayout></I
+></SPAN
>, like
- <TT
+ <TT
CLASS="LITERAL"
><pre></TT
>, more or less.
- </TD
+ </TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
-><itemizedlist></itemizdelist></I
+><itemizedlist></itemizedlist></I
+></SPAN
>, list with bullets.
- </TD
+ </TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><listitem></listitem></I
+></SPAN
>, member of the above.
- </TD
+ </TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><screen></screen></I
+></SPAN
>, screen output, implies
- <TT
+ <TT
CLASS="LITERAL"
><literallayout></TT
>.
- </TD
+ </TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><ulink url="example.com"></ulink></I
+></SPAN
>, like
- HTML <TT
+ HTML <TT
CLASS="LITERAL"
><a></TT
> tag.
- </TD
+ </TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><quote></quote></I
+></SPAN
>, for, doh, quoting text.
- </TD
+ </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"
CLASS="SECT2"
><A
NAME="DOCSTYLE"
->4.2. <SPAN
+>3.2. <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
> Documentation Style</A
></LI
><LI
><P
-> Tags delimiting a block of text should be on their own line.
- Like:
+> 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>
></LI
><LI
><P
-> Tags should be nested and step indented like:
- <P
+> Tags should be nested and step indented for block text like: (except
+ in-line tags)
+ <P
CLASS="LITERALLAYOUT"
> <para><br>
<itemizedlist><br>
><P
> Do not hesitate to make comments. Comments can either use the
<comment> element, or the <!-- --> style comment
- familiar from HTML.
+ 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 :).
+ 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 lenghty URLs for
+ 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, and HTML, but PDF, and others is always a
+ are just plain text, HTML, and PDF, but others are always a
future possibility. Be careful with URLs (<ulink>), and avoid
this mistake:
</P
><H2
CLASS="SECT2"
><A
-NAME="AEN173"
->4.3. Privoxy Custom Entities</A
+NAME="AEN217"
+>3.3. Privoxy Custom Entities</A
></H2
><P
> <SPAN
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
- <I
+ <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
>Privoxy</SPAN
> version string. You are strongly
encouraged to use these where possible. Some of these obviously
- require re-setting with each release. A sampling of custom entities are
- listed below. See any of the main docs for examples.
+ 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
><UL
><LI
><P
-> Re-cyclable <SPAN
+> Re- <SPAN
CLASS="QUOTE"
>"boilerplate"</SPAN
> text entities are defined like:
><TBODY
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
>p-version</I
+></SPAN
>: the <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
>
version string, e.g. <SPAN
CLASS="QUOTE"
->"2.9.13"</SPAN
+>"3.0.11"</SPAN
>.
</TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
>p-status</I
+></SPAN
>: the project status, either
<SPAN
CLASS="QUOTE"
->"ALPHA"</SPAN
+>"alpha"</SPAN
>, <SPAN
CLASS="QUOTE"
->"BETA"</SPAN
+>"beta"</SPAN
>, or <SPAN
CLASS="QUOTE"
->"STABLE"</SPAN
+>"stable"</SPAN
>.
</TD
></TR
><TR
><TD
-> <I
+> <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
+>"beta"</SPAN
>).
</TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
>p-stable</I
+></SPAN
>: just the opposite.
</TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
>p-text</I
+></SPAN
>: this doc is only generated as text.
</TD
></TR
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
+SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
ALIGN="left"
VALIGN="top"
><A
-HREF="quickstart.html"
+HREF="cvs.html"
+ACCESSKEY="P"
>Prev</A
></TD
><TD
VALIGN="top"
><A
HREF="index.html"
+ACCESSKEY="H"
>Home</A
></TD
><TD
VALIGN="top"
><A
HREF="coding.html"
+ACCESSKEY="N"
>Next</A
></TD
></TR
WIDTH="33%"
ALIGN="left"
VALIGN="top"
->Quickstart to Privoxy Development</TD
+>The CVS Repository</TD
><TD
WIDTH="34%"
ALIGN="center"
projects / privoxy.git / blobdiff