+ If you become part of the active development team, you will eventually
+ need write access to our holy grail, the CVS repository. One of the
+ team members will need to set this up for you. Please read
+ this chapter completely before accessing via CVS.
+ </para>
+
+ <sect2 id="cvsaccess"><title>Access to CVS</title>
+ <para>
+ The project's CVS repository is hosted on
+ <ulink url="http://sourceforge.net/">SourceForge.</ulink>
+ Please refer to the chapters 6 and 7 in
+ <ulink url="http://sourceforge.net/docman/?group_id=1">SF's site
+ documentation</ulink> for the technical access details for your
+ operating system. For historical reasons, the CVS server is
+ called <literal>ijbswa.cvs.sourceforge.net</literal>, the repository is
+ called <literal>ijbswa</literal>, and the source tree module is called
+ <literal>current</literal>.
+ </para>
+ </sect2>
+
+ <sect2 id="cvsbranches">
+ <title>Branches</title>
+ <para>
+ Within the CVS repository, there are modules and branches. As
+ mentioned, the sources are in the <literal>current</literal>
+ <quote>module</quote>. Other modules are present for platform specific
+ issues. There is a webview of the CVS hierarchy at <ulink
+ url="http://ijbswa.cvs.sourceforge.net/ijbswa/">http://ijbswa.cvs.sourceforge.net/ijbswa/</ulink>,
+ which might help with visualizing how these pieces fit together.
+ </para>
+ <para>
+ Branches are used to fork a sub-development path from the main trunk.
+ Within the <literal>current</literal> module where the sources are, there
+ is always at least one <quote>branch</quote> from the main trunk
+ devoted to a stable release series. The main trunk is where active
+ development takes place for the next stable series (e.g. 3.2.x).
+ So just prior to each stable series (e.g. 3.0.x), a branch is created
+ just for stable series releases (e.g. 3.0.0 -> 3.0.1 -> 3.0.2, etc).
+ Once the initial stable release of any stable branch has taken place,
+ this branch is <emphasis>only used for bugfixes</emphasis>, which have
+ had prior testing before being committed to CVS. (See <link
+ linkend="versionnumbers">Version Numbers</link> below for details on
+ versioning.)
+ </para>
+ <para>
+ At one time there were two distinct branches: stable and unstable. The
+ more drastic changes were to be in the unstable branch. These branches
+ have now been merged to minimize time and effort of maintaining two
+ branches.
+ </para>
+ <!--
+ <para>
+ This will result in at least two active branches, which means there may
+ be occasions that require the same (or similar) item to be
+ checked into to two different places (assuming its a bugfix and needs
+ fixing in both the stable and unstable trees). This also means that in
+ order to have access to both trees, both will have to be checked out
+ separately. Use the <literal>cvs -r</literal> flag to check out a
+ branch, e.g: <literal>cvs co -r v_3_0_branch current</literal>.
+ </para>
+ -->
+ </sect2>
+
+ <sect2 id="cvscommit"><title>CVS Commit Guidelines</title>
+ <para>
+ The source tree is the heart of every software project. Every effort must
+ be made to ensure that it is readable, compilable and consistent at all
+ times. There are differing guidelines for the stable branch and the
+ main development trunk, and we ask anyone with CVS access to strictly
+ adhere to the following guidelines:
+ </para>
+
+ <para>
+ Basic Guidelines, for all branches:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem><para>
+ Please don't commit even
+ a small change without testing it thoroughly first. When we're
+ close to a public release, ask a fellow developer to review your
+ changes.
+ </para></listitem>
+ <listitem><para>
+ Your commit message should give a concise overview of <emphasis>what you
+ changed</emphasis> (no big details) and <emphasis>why you changed it</emphasis>
+ Just check previous messages for good examples.
+ </para></listitem>
+ <listitem><para>
+ Don't use the same message on multiple files, unless it equally applies to
+ all those files.
+ </para></listitem>
+ <listitem><para>
+ If your changes span multiple files, and the code won't recompile unless
+ all changes are committed (e.g. when changing the signature of a function),
+ then commit all files one after another, without long delays in between.
+ If necessary, prepare the commit messages in advance.
+ </para></listitem>
+ <listitem><para>
+ Before changing things on CVS, make sure that your changes are in line
+ with the team's general consensus on what should be done.
+ </para></listitem>
+ <listitem>
+ <para>
+ Note that near a major public release, we get more cautious.
+ There is always the possibility to submit a patch to the <ulink
+ url="http://sourceforge.net/tracker/?atid=311118&group_id=11118&func=browse">patch
+ tracker</ulink> instead.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+<!--
+ <para>
+ Stable branches are handled with more care, especially after the
+ initial *.*.0 release, and we are just in bugfix mode. In addition to
+ the above, the below applies only to the stable branch (currently the
+ <literal>v_3_0_branch</literal> branch):
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Do not commit <emphasis>anything</emphasis> unless your proposed
+ changes have been well tested first, preferably by other members of the
+ project, or have prior approval of the project leaders or consensus
+ of the devel list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Where possible, bugfixes and changes should be tested in the main
+ development trunk first. There may be occasions where this is not
+ feasible, though.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Alternately, proposed changes can be submitted as patches to the patch tracker on
+ Sourceforge first: <ulink
+ url="http://sourceforge.net/tracker/?group_id=11118&atid=311118">http://sourceforge.net/tracker/?group_id=11118&atid=311118</ulink>.
+ Then ask for peer review.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Do not even think about anything except bugfixes. No new features!
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ -->
+ </sect2>
+
+ </sect1>
+
+ <!-- ~~~~~ New section ~~~~~ -->
+<sect1 id="documentation"><title>Documentation Guidelines</title>
+ <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>, 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>INSTALL</citetitle>,
+ <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.
+ </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>) are
+ maintained as plain text files in the top-level source directory.
+ </para>
+ <para>
+ 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
+ <filename>doc/webserver/*</filename>. And PDF version are kept in
+ <filename>doc/pdf/*</filename>.
+ </para>
+ <para>
+ Formal documents are built with the Makefile targets of
+ <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/text/</computeroutput> and to update all HTML
+ documents in <computeroutput>doc/webserver/</computeroutput>.
+ </para>
+ <para>
+ Documentation writers should please make sure documents build
+ successfully before committing to CVS, if possible.
+ </para>
+ <para>
+ How do you update the webserver (i.e. the pages on privoxy.org)?
+
+ <orderedlist numeration="arabic">
+ <listitem><para>
+ First, build the docs by running <computeroutput>make
+ dok</computeroutput> (or alternately <computeroutput>make
+ redhat-dok</computeroutput>). For PDF docs, do <computeroutput>make
+ dok-pdf</computeroutput>.
+ </para></listitem>
+ <listitem><para>
+ Run <computeroutput>make webserver</computeroutput> which copies all
+ files from <computeroutput>doc/webserver</computeroutput> to the
+ sourceforge webserver via scp.
+ </para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ Finished docs should be occasionally submitted to CVS
+ (<filename>doc/webserver/*/*.html</filename>) 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 <emphasis>after</emphasis> the <literal>$VERSION</literal> and
+ other release specific data in <filename>configure.in</filename> has been
+ updated (this is done just prior to a new release).
+ </para>
+
+<!-- ~~~~~ New section ~~~~~ -->
+<sect2 id="sgml">
+<title>Quickstart to Docbook and SGML</title>
+<para>
+ 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
+ <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 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>
+ Our documents use <quote>sections</quote> for the most part. Sections
+ will be processed into HTML headers (e.g. <literal>h1</literal> for
+ <literal>sect1</literal>). The <application>Docbook</application> 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 <literal>sect1</literal>,
+ <literal>sect2</literal>, and <literal>sect3</literal> will have TOC
+ entries, but <literal>sect4</literal> will not. Each section requires
+ a <literal><title></literal> element, and at least one
+ <literal><para></literal>. There is a limit of five section
+ levels in Docbook, but generally three should be sufficient for our
+ purposes.
+</para>
+
+<para>
+ Some common elements that you likely will use:
+</para>
+
+<para>
+ <simplelist>
+ <member>
+ <emphasis><para></para></emphasis>, paragraph delimiter. Most
+ text needs to be within paragraph elements (there are some exceptions).
+ </member>
+ <member>
+ <emphasis><emphasis></emphasis></emphasis>, the stylesheets
+ make this italics.
+ </member>
+ <member>
+ <emphasis><filename></filename></emphasis>, files and directories.
+ </member>
+ <member>
+ <emphasis><command></command></emphasis>, command examples.
+ </member>
+ <member>
+ <emphasis><literallayout></literallayout></emphasis>, like
+ <literal><pre></literal>, more or less.
+ </member>
+ <member>
+ <emphasis><itemizedlist></itemizedlist></emphasis>, list with bullets.
+ </member>
+ <member>
+ <emphasis><listitem></listitem></emphasis>, member of the above.
+ </member>
+ <member>
+ <emphasis><screen></screen></emphasis>, screen output, implies
+ <literal><literallayout></literal>.
+ </member>
+ <member>
+ <emphasis><ulink url="example.com"></ulink></emphasis>, like
+ HTML <literal><a></literal> tag.
+ </member>
+ <member>
+ <emphasis><quote></quote></emphasis>, for, doh, quoting text.
+ </member>
+ </simplelist>
+</para>
+
+<para>
+ Look at any of the existing docs for examples of all these and more.
+</para>
+
+<para>
+ You might also find <quote><ulink
+ url="http://opensource.bureau-cornavin.com/crash-course/index.html">Writing Documentation
+ Using DocBook - A Crash Course</ulink></quote> useful.
+</para>
+</sect2>
+
+<!-- ~~~~~ New section ~~~~~ -->
+ <sect2 id="docstyle">
+ <title><application>Privoxy</application> Documentation Style</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ Here it is:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ All tags should be lower case.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Tags delimiting a <emphasis>block</emphasis> of text (even small
+ blocks) should be on their own line. Like:
+ <literallayout>
+ <para>
+ Some text goes here.
+ </para>
+ </literallayout>
+ Tags marking individual words, or few words, should be in-line:
+ <literallayout>
+ Just to <emphasis>emphasize</emphasis>, some text goes here.
+ </literallayout>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Tags should be nested and step indented for block text like: (except
+ in-line tags)
+ <literallayout>
+ <para>
+ <itemizedlist>
+ <para>
+ <listitem>
+ Some text goes here in our list example.
+ </listitem>
+ </para>
+ </itemizedlist>
+ </para>
+ </literallayout>
+ This makes it easier to find the text amongst the tags ;-)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 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>.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ We have an international audience. Refrain from slang, or English
+ idiosyncrasies (too many to list :). Humor also does not translate
+ well sometimes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 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.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Our documents are available in differing formats. Right now, they
+ are just plain text, HTML, and PDF, but others are always a
+ future possibility. Be careful with URLs (<ulink>), and avoid
+ this mistake:
+ </para>
+ <para>
+ My favorite site is <ulink url="http://example.com">here</ulink>.
+ </para>
+ <para>
+ This will render as <quote>My favorite site is here</quote>, which is
+ not real helpful in a text doc. Better like this:
+ </para>
+ <para>
+ My favorite site is <ulink url="http://example.com">example.com</ulink>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ All documents should be spell checked occasionally.
+ <application>aspell</application> can check SGML with the
+ <literal>-H</literal> option. (<application>ispell</application> I think
+ too.)
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+
+ </sect2>
+
+
+ <!-- ~~~~~ New section ~~~~~ -->
+
+ <sect2><title>Privoxy Custom Entities</title>
+ <para>
+ <application>Privoxy</application> documentation is using
+ a number of customized <quote>entities</quote> to facilitate
+ documentation maintenance.
+ </para>
+ <para>
+ We are using a set of <quote>boilerplate</quote> 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
+ <emphasis>generic</emphasis>. That is the purpose; so it can be used in varying
+ contexts without additional modifications.
+ </para>
+ <para>
+ We are also using what <application>Docbook</application> calls
+ <quote>internal entities</quote>. These are like variables in
+ programming. Well, sort of. For instance, we have the
+ <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 (done by the Makefile). A sampling of
+ custom entities are listed below. See any of the main docs for examples.
+ </para>