<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 CVS Repository" href="cvs.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=utf-8">
+ <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">
<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="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>
<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=
+ "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.1</i> (man page),
+ <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
<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>
+ 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 CVS. HTML versions are also being kept in CVS under <tt class=
+ 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 CVS, if
+ <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</samp>.</p>
+ <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 scp.</p>
+ "COMPUTEROUTPUT">doc/webserver</samp> to the sourceforge webserver via ssh.</p>
</li>
</ol>
- <p>Finished docs should be occasionally submitted to CVS (<tt class="FILENAME">doc/webserver/*/*.html</tt>) so that
+ <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
</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>
+ <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
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:
+ </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.<br>
-
- </p>
+ 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>
</listitem><br>
</para><br>
</itemizedlist><br>
- </para><br>
- </p>This makes it easier to find the text amongst the tags ;-)
+ </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
</ul>
</div>
<div class="SECT2">
- <h2 class="SECT2"><a name="AEN207" id="AEN207">3.3. Privoxy Custom Entities</a></h2>
+ <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
<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
+ "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>
<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.27"</span>.</td>
+ "APPLICATION">Privoxy</span> version string, e.g. <span class="QUOTE">"3.0.30"</span>.</td>
</tr>
<tr>
<td><span class="emphasis"><i class="EMPHASIS">p-status</i></span>: the project status, either
<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="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 CVS Repository</td>
+ <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>
projects / privoxy.git / blobdiff