<!entity contacting SYSTEM "contacting.sgml">
<!entity copyright SYSTEM "copyright.sgml">
<!entity license SYSTEM "license.sgml">
-<!entity p-version "2.9.15">
+<!entity p-version "2.9.18">
<!entity p-status "beta">
<!entity % p-not-stable "INCLUDE">
<!entity % p-stable "IGNORE">
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: developer-manual.sgml,v 1.46.2.3 2002/05/28 04:32:45 hal9 Exp $
+ $Id: developer-manual.sgml,v 1.46.2.4 2002/05/29 00:30:59 mal0rd Exp $
Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
See LICENSE.
</pubdate>
- <pubdate>$Id: developer-manual.sgml,v 1.46.2.3 2002/05/28 04:32:45 hal9 Exp $</pubdate>
+ <pubdate>$Id: developer-manual.sgml,v 1.46.2.4 2002/05/29 00:30:59 mal0rd Exp $</pubdate>
<!--
<ulink url="../faq/index.html"><citetitle>FAQ</citetitle></ulink>, and, of
course this, the <citetitle>developer-manual</citetitle> in this format.
The <citetitle>README</citetitle>, <citetitle>AUTHORS</citetitle>
- <citetitle>privoxy.1</citetitle> (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, <filename>index.html</filename>, the
- <application>Privoxy</application> home page, is maintained as SGML.
+ <citetitle>privoxy.1</citetitle> (man page), and
+ <citetitle>config</citetitle> files are also now maintained as Docbook
+ SGML. These files, when built, in the top-level source directory are
+ generated files! Also, the <application>Privoxy</application> <filename>index.html</filename> (and a
+ variation on this file, <filename>privoxy-index.html</filename>,
+ meant for inclusion with doc packages), are maintained as SGML as well.
<emphasis>DO NOT edit these directly</emphasis>. Edit the SGML source, or
contact someone involved in the documentation (at present Stefan and
Hal).
</para>
+ <para>
+ <filename>config</filename> requires some special handling. The reason it
+ is maintained this way is so that the extensive comments in the file
+ mirror those in <citetitle>user-manual</citetitle>. 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 <filename>config.new</filename>,
+ which should be reviewed for errors and mis-formatting. Once satisfied
+ that it is correct, then it should be hand copied to
+ <filename>config</filename>.
+
+ </para>
<para>
Other, less formal documents (e.g. <filename>LICENSE</filename>,
<filename>INSTALL</filename>) are maintained as plain text files in the
<para><emphasis>Example for file comments:</emphasis></para>
<programlisting>
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.46.2.3 2002/05/28 04:32:45 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.46.2.4 2002/05/29 00:30:59 mal0rd Exp $";
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
<programlisting>
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.46.2.3 2002/05/28 04:32:45 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.46.2.4 2002/05/29 00:30:59 mal0rd Exp $"
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
<listitem>
<para>
Increment the version number (point from odd to even in development
- branches!) in <filename>configure.in</filename>.
+ branches!) in <filename>configure.in</filename>. (RPM spec files
+ will need to be incremented as well.)
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
- If the HTML documentation is not in sync with the SGML sources
- you need to regenerate and upload it to the webserver. (If in
- doubt, just do it.) See the Section "Updating the webserver" in
- this manual for details.
+ All documentation should be rebuild after the version bump.
+ Finished docs should be then be committed to CVS (for those
+ without the ability to build these). Some docs may require
+ rather obscure processing tools. <filename>config</filename>,
+ the man page (and the html version of the man page), and the PDF docs
+ fall in this category. REAMDE, the man page, AUTHORS, and config
+ should all also be committed to CVS for other packageers. The
+ formal docs should be uploaded to the webserver. See the
+ Section "Updating the webserver" in this manual for details.
</para>
</listitem>
+ <listitem>
+ <para>
+ All developers should look at the <filename>ChangeLog</filename> and
+ make sure noteworthy changes are referenced.
+ </para>
+ </listitem>
<listitem>
<para>
<emphasis>Commit all files that were changed in the above steps!</emphasis>
maintainers to do this if you can't).
</para>
</listitem>
+ <listitem>
+ <para>
+ Packagers should do a <quote>clean</quote> install of their
+ package after building it. So any previous installs should be
+ removed first to ensure the integrity of the newly built package.
+ Then run the package for a while to make sure there are no
+ obvious problems, before uploading.
+ </para>
+ </listitem>
</itemizedlist>
</para>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: developer-manual.sgml,v $
+ Revision 1.46.2.4 2002/05/29 00:30:59 mal0rd
+ Fixed a little formatting. Clarified debian section.
+
Revision 1.46.2.3 2002/05/28 04:32:45 hal9
Change hints on bundling index.html to privoxy-index.html