-<!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 Git Repository" href="git.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="git.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" id="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="https://www.docbook.org/" target=
- "_top">Docbook</a>, the Docbook DTD's and the Docbook modular stylesheets (or comparable alternatives), 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.8</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.</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 Git. HTML versions are also being kept in Git under <tt class=
- "FILENAME">doc/webserver/*</tt>.</p>
- <p>Formal documents are built with the Makefile targets of <samp class="COMPUTEROUTPUT">make dok</samp>. 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 Git, if
- possible.</p>
- <p>How do you update the webserver (i.e. the pages on privoxy.org)?</p>
- <ol type="1">
- <li>
- <p>First, build the docs by running <samp class="COMPUTEROUTPUT">make dok dok-tidy</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 ssh.</p>
- </li>
- </ol>
- <p>Finished docs should be occasionally submitted to Git (<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" id="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>
- <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>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=
- "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>"</span> useful.</p>
- </div>
- <div class="SECT2">
- <h2 class="SECT2"><a name="DOCSTYLE" id="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>
- <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>
- <p class="LITERALLAYOUT"> <para><br>
- Some text goes here.<br>
- </para></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.</p>
- </li>
- <li>
- <p>Tags should be nested and step indented for block text like: (except in-line tags)</p>
- <p class="LITERALLAYOUT"> <para><br>
- <itemizedlist><br>
- <para><br>
- <listitem><br>
- Some text goes here in our list example.<br>
+<!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 Git Repository"
+HREF="git.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="git.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="https://www.docbook.org/"
+TARGET="_top"
+>Docbook</A
+>, the Docbook
+ DTD's and the Docbook modular stylesheets (or comparable alternatives),
+ 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.8</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.
+ </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
+ Git. HTML versions are also being kept in Git under
+ <TT
+CLASS="FILENAME"
+>doc/webserver/*</TT
+>.
+ </P
+><P
+> Formal documents are built with the Makefile targets of
+ <SAMP
+CLASS="COMPUTEROUTPUT"
+>make dok</SAMP
+>.
+ 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 Git, if possible.
+ </P
+><P
+> How do you update the webserver (i.e. the pages on privoxy.org)?
+ </P
+><P
+></P
+><OL
+TYPE="1"
+><LI
+><P
+> First, build the docs by running <SAMP
+CLASS="COMPUTEROUTPUT"
+>make
+ dok dok-tidy</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 ssh.
+ </P
+></LI
+></OL
+><P
+> Finished docs should be occasionally submitted to Git
+ (<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
+><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
+> Look at any of the existing docs for examples of all these and more.</P
+><P
+> You might also find
- </listitem><br>
- </para><br>
- </itemizedlist><br>
- </para></p>
- <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 and/or HTML, 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>
- </div>
- <div class="SECT2">
- <h2 class="SECT2"><a name="CUSTOM-ENTITIES" id="CUSTOM-ENTITIES">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>
- <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>
- <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.34"</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>
- </li>
- </ul>
- <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="git.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 Git 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>
+ <SPAN
+CLASS="QUOTE"
+>"<A
+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
+>"</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
+><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
+><P
+CLASS="LITERALLAYOUT"
+> <para><br>
+ Some text goes here.<br>
+ </para></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.</P
+></LI
+><LI
+><P
+> Tags should be nested and step indented for block text like: (except
+ in-line tags)
+ </P
+><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></P
+><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 and/or HTML, 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
+></DIV
+><DIV
+CLASS="SECT2"
+><H2
+CLASS="SECT2"
+><A
+NAME="CUSTOM-ENTITIES"
+>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
+><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.34"</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
+> 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="git.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 Git 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
+>
\ No newline at end of file
projects / privoxy.git / blobdiff