+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Documentation Guidelines</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
-"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
><H1
CLASS="SECT1"
><A
-NAME="DOCUMENTATION">3. Documentation Guidelines</H1
+NAME="DOCUMENTATION"
+>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"
</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
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
+ dok</SAMP
+> (or alternately <SAMP
CLASS="COMPUTEROUTPUT"
>make
- redhat-dok</TT
->). For PDF docs, do <TT
+ redhat-dok</SAMP
+>). For PDF docs, do <SAMP
CLASS="COMPUTEROUTPUT"
>make
- dok-pdf</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
CLASS="EMPHASIS"
>after</I
></SPAN
-> the <TT
+> the <VAR
CLASS="LITERAL"
->$VERSION</TT
+>$VERSION</VAR
> and
other release specific data in <TT
CLASS="FILENAME"
><H2
CLASS="SECT2"
><A
-NAME="SGML">3.1. Quickstart to Docbook and SGML</H2
+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
CLASS="QUOTE"
>"closed"</SPAN
>. If not, you
- will likely generate errors. Example: <TT
+ will likely generate errors. Example: <VAR
CLASS="LITERAL"
><title>My
- Title</title></TT
+ Title</title></VAR
>. They are also case-insensitive, but we
strongly suggest using all lower case. This keeps compatibility with
[Docbook] <SPAN
CLASS="QUOTE"
>"sections"</SPAN
> for the most part. Sections
- will be processed into HTML headers (e.g. <TT
+ will be processed into HTML headers (e.g. <VAR
CLASS="LITERAL"
->h1</TT
+>h1</VAR
> for
- <TT
+ <VAR
CLASS="LITERAL"
->sect1</TT
+>sect1</VAR
>). 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
+ TOC's are set to a depth of three. Meaning <VAR
CLASS="LITERAL"
->sect1</TT
+>sect1</VAR
>,
- <TT
+ <VAR
CLASS="LITERAL"
->sect2</TT
->, and <TT
+>sect2</VAR
+>, and <VAR
CLASS="LITERAL"
->sect3</TT
+>sect3</VAR
> will have TOC
- entries, but <TT
+ entries, but <VAR
CLASS="LITERAL"
->sect4</TT
+>sect4</VAR
> will not. Each section requires
- a <TT
+ a <VAR
CLASS="LITERAL"
-><title></TT
+><title></VAR
> element, and at least one
- <TT
+ <VAR
CLASS="LITERAL"
-><para></TT
+><para></VAR
>. There is a limit of five section
levels in Docbook, but generally three should be sufficient for our
purposes.</P
><literallayout></literallayout></I
></SPAN
>, like
- <TT
+ <VAR
CLASS="LITERAL"
-><pre></TT
+><pre></VAR
>, more or less.
</TD
></TR
><screen></screen></I
></SPAN
>, screen output, implies
- <TT
+ <VAR
CLASS="LITERAL"
-><literallayout></TT
+><literallayout></VAR
>.
</TD
></TR
><ulink url="example.com"></ulink></I
></SPAN
>, like
- HTML <TT
+ HTML <VAR
CLASS="LITERAL"
-><a></TT
+><a></VAR
> tag.
</TD
></TR
><H2
CLASS="SECT2"
><A
-NAME="DOCSTYLE">3.2. <SPAN
+NAME="DOCSTYLE"
+>3.2. <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> Documentation Style</H2
+> 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
CLASS="APPLICATION"
>aspell</SPAN
> can check SGML with the
- <TT
+ <VAR
CLASS="LITERAL"
->-H</TT
+>-H</VAR
> option. (<SPAN
CLASS="APPLICATION"
>ispell</SPAN
><H2
CLASS="SECT2"
><A
-NAME="AEN233">3.3. Privoxy Custom Entities</H2
+NAME="AEN233"
+>3.3. Privoxy Custom Entities</A
+></H2
><P
> <SPAN
CLASS="APPLICATION"
>"internal entities"</SPAN
>. These are like variables in
programming. Well, sort of. For instance, we have the
- <TT
+ <VAR
CLASS="LITERAL"
->p-version</TT
+>p-version</VAR
> entity that contains the current
<SPAN
CLASS="APPLICATION"
> text entities are defined like:
</P
><P
-> <TT
+> <VAR
CLASS="LITERAL"
-><!entity supported SYSTEM "supported.sgml"></TT
+><!entity supported SYSTEM "supported.sgml"></VAR
>
</P
><P
>supported.sgml</TT
> is available for inclusion anywhere
in the doc. To make this happen, just reference the now defined
- entity: <TT
+ entity: <VAR
CLASS="LITERAL"
->&supported;</TT
+>&supported;</VAR
> (starts with an ampersand
and ends with a semi-colon), and the contents will be dumped into
the finished doc at that point.
>
version string, e.g. <SPAN
CLASS="QUOTE"
->"3.1.1"</SPAN
+>"3.0.3"</SPAN
>.
</TD
></TR
projects / privoxy.git / blobdiff