This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $
+ $Id: developer-manual.sgml,v 1.30 2002/04/11 09:24:53 oes Exp $
Written by and Copyright (C) 2001 the SourceForge
Privoxy team. http://www.privoxy.org/
<artheader>
<title>Privoxy Developer Manual</title>
- <pubdate>$Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $</pubdate>
+ <pubdate>$Id: developer-manual.sgml,v 1.30 2002/04/11 09:24:53 oes Exp $</pubdate>
<authorgroup>
<author>
<para>
All formal documents are maintained in docbook SGML and located in the
<computeroutput>doc/source/*</computeroutput> directory. You will need
- <ulink url="http://www.docbook.org">docbook</ulink> and the docbook
- stylesheets (or comparable alternatives), and either
- <application>jade</application> or <application>openjade</application>
- (recommended) installed in order to build docs from source. Currently
- there is <ulink
+ <ulink url="http://www.docbook.org">Docbook</ulink>, the Docbook
+ DTD's and the Docbook modular stylesheets (or comparable alternatives),
+ and either <application>jade</application> or
+ <application>openjade</application> (recommended) installed in order to
+
build docs from source. Currently there is <ulink
url="../user-manual/index.html"><citetitle>user-manual</citetitle></ulink>,
- <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 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. <emphasis>DO NOT edit these
- directly</emphasis>. Edit the SGML source, or contact someone
- involved in the documentation (at present Stefan and Hal).
+ <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.
+ <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>
- Other, less formal documents (e.g. LICENSE, INSTALL) are maintained as
- plain text files in the toplevel source directory. At least for the
- time being.
+ Other, less formal documents (e.g. <filename>LICENSE</filename>,
+ <filename>INSTALL</filename>) are maintained as plain text files in the
+ toplevel source directory. At least for the time being.
</para>
<para>
Packagers are encouraged to include this documentation. For those without
<computeroutput>make dok</computeroutput>, or alternately
<computeroutput>make redhat-dok</computeroutput>. If you have problems,
try both. The build process uses the document SGML sources in
- <computeroutput>doc/source/*</computeroutput> to update all text files in
+ <computeroutput>doc/source/*/*</computeroutput> to update all text files in
<computeroutput>doc/text/</computeroutput> and to update all HTML
documents in <computeroutput>doc/webserver/</computeroutput>.
</para>
<title>Quickstart to Docbook and SGML</title>
<para>
If you are not familiar with SGML, it is a markup language similar to HTML.
- In fact, HTML is an SGML application. Both use <quote>tags</quote>
- to format text and other content. SGML tags are much more varied,
- and flexible, but do much of the same kinds of things. The tags,
- or <quote>elements</quote>, are definable in SGML. There is no
- set <quote>standards</quote>. Since we are using
- <application>Docbook</application>, our tags are those that are
- defined by <application>Docbook</application>. Much of how the
- finish document is rendered is determined by the <quote>stylesheets</quote>.
- The stylesheets determine how each tag gets translated to HTML, or
- other formats.
+ 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
+ <quote>tags</quote> 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 <quote>elements</quote>, are definable in SGML. There is no set
+ <quote>standards</quote>. Since we are using
+ <application>Docbook</application>, our tags are those that are defined by
+ <application>Docbook</application>. Much of how the finish document is
+ rendered is determined by the <quote>stylesheets</quote>.
+ The stylesheets determine how each tag gets translated to HTML, or other
+ formats.
</para>
<para>
- Tags in SGML need to be always <quote>closed</quote>. If not, you
- will likely generate errors. Example:
- <literal><title>My Title</title></literal>. They are
- also case-insensitive, but we strongly suggest using all lower
-
case. This keeps compatibility with [Docbook] <application>XML</application>.
+ Tags in Docbook SGML need to be always <quote>closed</quote>. If not, you
+ will likely generate errors. Example: <literal><title>My
+ Title</title></literal>. They are also case-insensitive, but we
+ strongly suggest using all lower case. This keeps compatibility with
+ [Docbook] <application>XML</application>.
</para>
<para>
<simplelist>
<member>
<emphasis><para></para></emphasis>, paragraph delimiter. Most
- text needs to be within paragraph elements.
+ text needs to be within paragraph elements (there are some exceptions).
</member>
<member>
- <emphasis><emphasis></emphasis></emphasis>, stylesheets make this
+ <emphasis><emphasis></emphasis></emphasis>, the stylesheets make this
italics.
</member>
<member>
</listitem>
<listitem>
<para>
- Tags delimiting a <emphasis>block</emphasis> of text should be on their
- own line. Like:
+ Tags delimiting a <emphasis>block</emphasis> of text (even small
+ blocks) should be on their own line. Like:
<literallayout>
<para>
Some text goes here.
</listitem>
<listitem>
<para>
- Tags should be nested and step indented like (except in-line tags):
- <literallayout>
+ Tags should be nested and step indented for block text like: (except
+ in-line tags)
+ <literallayout>
<para>
<itemizedlist>
<para>
<literal>p-version</literal> entity that contains the current
<application>Privoxy</application> version string. You are strongly
encouraged to use these where possible. Some of these obviously
- require re-setting with each release. A sampling of custom entities are
- listed below. See any of the main docs for examples.
+ 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.
</para>
<para>
<para><emphasis>Example for file comments:</emphasis></para>
<programlisting>
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.30 2002/04/11 09:24:53 oes Exp $";
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
<programlisting>
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.25 2002/04/06 05:07:28 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.30 2002/04/11 09:24:53 oes Exp $"
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
<filename>ncftpput</filename> (ncftp), <filename>scp</filename> (ssh),
<filename>gmake</filename> (GNU's version of make), autoconf, cvs, ???.
</para>
+ <para>
+ Replace X, Y and Z with the actual version number (X = major, Y = minor, Z = point):
+ </para>
<sect2 id="beforerelease">
<title>Before the Release</title>
<para>
The following <emphasis>must be done by one of the
- developers</emphasis> prior to each new release:
+ developers</emphasis> prior to each new release.
</para>
<para>
<itemizedlist>
<listitem>
<para>
Increment the version number in <filename>configure.in</filename> in
- CVS. Also, the RPM release number in
- <filename>configure.in</filename>. Do NOT touch version information
- after export from CVS. <emphasis>All packages</emphasis> will use the
- version and release data from <filename>configure.in</filename>.
+ CVS. Also, inrease or reset the RPM release number in
+ <filename>configure.in</filename> as appropriate. Do <emphasis>NOT</emphasis>
+ touch version information after export from CVS.
+ <emphasis>All packages</emphasis> will use the version and release data
+ from <filename>configure.in</filename>.
Local files should not be changed, except prior to a CVS commit!!!
This way we are all on the same page!
</para>
line: '$required_actions_file_version = "A.B";'
</para>
</listitem>
+ <listitem>
+ <para>
+ <emphasis>Commit all files that were changed in the above steps!</emphasis>
+ </para>
+ </listitem>
<listitem>
<para>
Tag all files in CVS with the version number with
- <quote><command>cvs tag v_X_Y_Z</command></quote> (where X = major, Y
- = minor, Z = point). Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work)
- etc.
+ <quote><command>cvs tag v_X_Y_Z</command></quote>.
+ Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
</para>
</listitem>
<listitem>
</para>
<para>
<programlisting>
- cd current
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+ cd current
</programlisting>
</para>
<para>
</para>
<para>
<programlisting>
- cd current
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
cd ..
</para>
<para>
<programlisting>
- cd current
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+ cd current
</programlisting>
</para>
<para>
</para>
<para>
<programlisting>
- cd current
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+ cd current
</programlisting>
</para>
<para>
</para>
<para>
<programlisting>
- cd current
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+ cd current
</programlisting>
</para>
<para>
</para>
<para>
<programlisting>
- cd current
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
cd ..
</programlisting>
</para>
<para>
- Choose the right operating system. If you have downloaded Privoxy
- before,
+ Choose the right operating system.
</para>
<para>
<programlisting>
- cd current
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+ cd current
</programlisting>
</para>
<para>
- If not, please <ulink
- url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
- Privoxy via CVS first</ulink>. Run:
+ Run:
</para>
<para>
<programlisting>
<sect2 id="newrelease-tarball"><title>Tarball</title>
<para>
- Ensure that you have the latest code version. Hence run:
+ Ensure that you have the right code version. Hence run:
</para>
<para>
<programlisting>
- cd current
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+ cd current
</programlisting>
</para>
<para>
</para>
<para>
<programlisting>
- make clobber
autoheader && autoconf && ./configure
</programlisting>
</para>
</para>
<para>
<programlisting>
- cd current
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+ cd current
</programlisting>
</para>
<para>
</para>
<para>
<programlisting>
- cd current
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+ cd current
</programlisting>
</para>
<para>
</para>
<para>
<programlisting>
- cd current
cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+ cd current
</programlisting>
</para>
<para>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: developer-manual.sgml,v $
+ Revision 1.30 2002/04/11 09:24:53 oes
+ nits
+
+ Revision 1.29 2002/04/10 18:45:14 swa
+ generated
+
+ Revision 1.28 2002/04/08 22:59:26 hal9
+ Version update. Spell chkconfig correctly :)
+
+ Revision 1.27 2002/04/08 15:31:18 hal9
+ Touch ups to documentation section.
+
+ Revision 1.26 2002/04/07 23:50:08 hal9
+ Documentation changes to reflect HTML docs now in CVS, and new generated files
+ list.
+
Revision 1.25 2002/04/06 05:07:28 hal9
-Add privoxy-man-page.sgml, for man page.
-Add authors.sgml for AUTHORS (and p-authors.sgml)
projects / privoxy.git / blobdiff