<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
-
<html>
<head>
<title>Documentation Guidelines</title>
<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=us-ascii">
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
-
<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
"#840084" alink="#0000FF">
<div class="NAVHEADER">
<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" 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="http://www.docbook.org" target="_top">Docbook</a>, the Docbook
"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
"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>.</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 CVS, 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</samp>.</p>
</li>
-
<li>
<p>Run <samp class="COMPUTEROUTPUT">make webserver</samp> which
copies all files from <samp class=
via scp.</p>
</li>
</ol>
-
<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
"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
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=
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>
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,
</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=
"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><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>
</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>
</p>This makes it easier
to find the text amongst the tags ;-)
</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=
</li>
</ul>
</div>
-
<div class="SECT2">
- <h2 class="SECT2"><a name="AEN208" id="AEN208">3.3. Privoxy Custom
+ <h2 class="SECT2"><a name="AEN207" id="AEN207">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
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
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
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.23"</span>.</td>
+ <span class="QUOTE">"3.0.27"</span>.</td>
</tr>
-
<tr>
<td><span class="emphasis"><i class=
"EMPHASIS">p-status</i></span>: the project status, either
"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
</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="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>
projects / privoxy.git / blobdiff