+<!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.64
-"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
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"
VALIGN="bottom"
><A
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"
->5. Documentation Guidelines</A
+>3. Documentation Guidelines</A
></H1
><P
> All formal documents are maintained in Docbook SGML and located in the
- <TT
+ <SAMP
CLASS="COMPUTEROUTPUT"
->doc/source/*</TT
+>doc/source/*</SAMP
> directory. You will need
<A
HREF="http://www.docbook.org"
TARGET="_top"
>Docbook</A
->, the Docbook
+>, the Docbook
DTD's and the Docbook modular stylesheets (or comparable alternatives),
and either <SPAN
CLASS="APPLICATION"
>, <I
CLASS="CITETITLE"
>AUTHORS</I
->
+>,
+ <I
+CLASS="CITETITLE"
+>INSTALL</I
+>,
<I
CLASS="CITETITLE"
>privoxy.1</I
-> (man page) files are also now maintained
- as Docbook SGML. The finished files are all in the top-level source
- directory are generated files! Also, <TT
+> (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
->, the
+> (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="APPLICATION"
->Privoxy</SPAN
-> home page, is maintained as SGML.
- <I
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
>DO NOT edit these directly</I
+></SPAN
>. Edit the SGML source, or
- contact someone involved in the documentation (at present Stefan and
- Hal).
+ contact someone involved in the documentation.
</P
><P
-> Other, less formal documents (e.g. <TT
+> <TT
CLASS="FILENAME"
->LICENSE</TT
+>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"
->INSTALL</TT
->) are maintained as plain text files in the
- top-level source directory. At least for the time being.
+>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 now being kept in CVS under
+ CVS. HTML versions are also being kept in CVS under
<TT
CLASS="FILENAME"
>doc/webserver/*</TT
</P
><P
> Formal documents are built with the Makefile targets of
- <TT
-CLASS="COMPUTEROUTPUT"
->make dok</TT
->, or alternately
- <TT
+ <SAMP
CLASS="COMPUTEROUTPUT"
->make redhat-dok</TT
->. If you have problems,
- try both. The build process uses the document SGML sources in
- <TT
+>make dok</SAMP
+>.
+ The build process uses the document SGML sources in
+ <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
</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 <TT
+> First, build the docs by running <SAMP
CLASS="COMPUTEROUTPUT"
>make
- dok</TT
-> (or alternately <TT
-CLASS="COMPUTEROUTPUT"
->make
- redhat-dok</TT
->).
+ dok</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
></LI
></OL
->
- </P
><P
> Finished docs should be occasionally submitted to CVS
(<TT
CLASS="FILENAME"
>doc/webserver/*/*.html</TT
->) so that those without
+>) 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 <I
+ do this <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
>after</I
+></SPAN
> the <TT
CLASS="LITERAL"
>$VERSION</TT
CLASS="SECT2"
><A
NAME="SGML"
->5.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.
- Actually, not a mark up language per se, but a language used to define
+> 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"
<SPAN
CLASS="APPLICATION"
>Docbook</SPAN
->, our tags are those that are defined by
+>, our tags are those that are defined by
<SPAN
CLASS="APPLICATION"
>Docbook</SPAN
will be processed into HTML headers (e.g. <TT
CLASS="LITERAL"
>h1</TT
-> for
+> for
<TT
CLASS="LITERAL"
>sect1</TT
CLASS="APPLICATION"
>Docbook</SPAN
> stylesheets
- will use these to also generate the Table of Contents for each doc. Our
+ 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
+> will have TOC
entries, but <TT
CLASS="LITERAL"
>sect4</TT
-> will not. Each section requires
+> will not. Each section requires
a <TT
CLASS="LITERAL"
><title></TT
-> element, and at least one
+> 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
+>. 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
+> 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
->, paragraph delimiter. Most
+></SPAN
+>, paragraph delimiter. Most
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
+></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
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><command></command></I
+></SPAN
>, command examples.
</TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><literallayout></literallayout></I
->, like
+></SPAN
+>, like
<TT
CLASS="LITERAL"
><pre></TT
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><itemizedlist></itemizedlist></I
+></SPAN
>, list with bullets.
</TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><listitem></listitem></I
+></SPAN
>, member of the above.
</TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><screen></screen></I
->, screen output, implies
+></SPAN
+>, screen output, implies
<TT
CLASS="LITERAL"
><literallayout></TT
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><ulink url="example.com"></ulink></I
->, like
+></SPAN
+>, like
HTML <TT
CLASS="LITERAL"
><a></TT
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
><quote></quote></I
->, for, doh, quoting text.
+></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
+> You might also find
+
+ <SPAN
CLASS="QUOTE"
>"<A
-HREF="http://www.bureau-cornavin.com/opensource/crash-course/"
+HREF="https://web.archive.org/web/20160315230758/http://opensource.bureau-cornavin.com/crash-course/index.html"
TARGET="_top"
->Writing Documentation
- Using DocBook - A Crash Course</A
+> Writing Documentation Using DocBook - A Crash Course</A
>"</SPAN
> useful.</P
></DIV
CLASS="SECT2"
><A
NAME="DOCSTYLE"
->5.2. <SPAN
+>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
+> 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
></LI
><LI
><P
-> Tags delimiting a <I
+> 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
+ </P
+><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
+><P
+> Tags marking individual words, or few words, should be in-line:
+ </P
+><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
+ in-line tags)
+ </P
+><P
CLASS="LITERALLAYOUT"
> <para><br>
<itemizedlist><br>
</itemizedlist><br>
</para><br>
</P
->
- This makes it easier to find the text amongst the tags ;-)
+><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
+> 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
+> 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
+> 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
><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
- future possibility. Be careful with URLs (<ulink>), and avoid
+> 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:
</P
><P
> This will render as <SPAN
CLASS="QUOTE"
>"My favorite site is here"</SPAN
->, which is
+>, which is
not real helpful in a text doc. Better like this:
</P
><P
</P
></LI
></UL
->
- </P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
-NAME="AEN212"
->5.3. Privoxy Custom Entities</A
+NAME="AEN205"
+>3.3. Privoxy Custom Entities</A
></H2
><P
> <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> documentation is using
+> documentation is using
a number of customized <SPAN
CLASS="QUOTE"
>"entities"</SPAN
-> to facilitate
- documentation maintenance.
+> to facilitate
+ documentation maintenance.
</P
><P
> We are using a set of <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
->. That is the purpose; so it can be used in varying
+></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
+> calls
<SPAN
CLASS="QUOTE"
>"internal entities"</SPAN
->. These are like variables in
+>. 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
+> 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
+> 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
<TT
CLASS="FILENAME"
>supported.sgml</TT
-> is available for inclusion anywhere
- in the doc. To make this happen, just reference the now defined
+> 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
+> (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
><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.14"</SPAN
+>"3.0.27"</SPAN
>.
</TD
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
>p-status</I
->: the project status, either
+></SPAN
+>: the project status, either
<SPAN
CLASS="QUOTE"
>"alpha"</SPAN
></TR
><TR
><TD
-> <I
+> <SPAN
+CLASS="emphasis"
+><I
CLASS="EMPHASIS"
>p-not-stable</I
->: use to conditionally include
+></SPAN
+>: use to conditionally include
text in <SPAN
CLASS="QUOTE"
>"not stable"</SPAN
></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
></P
></LI
></UL
->
- </P
><P
-> There are others in various places that are defined for a specific
+> There are others in various places that are defined for a specific
purpose. Read the source!
</P
></DIV
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
+SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
VALIGN="top"
><A
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
projects / privoxy.git / blobdiff