developer-manual.sgml: Properly close a section
[privoxy.git] / doc / source / developer-manual.sgml
1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
2 <!entity % dummy "IGNORE">
3 <!entity supported SYSTEM "supported.sgml">
4 <!entity newfeatures SYSTEM "newfeatures.sgml">
5 <!entity p-intro SYSTEM "privoxy.sgml">
6 <!entity history SYSTEM "history.sgml">
7 <!entity seealso SYSTEM "seealso.sgml">
8 <!entity p-version "3.0.25">
9 <!entity p-status "beta">
10 <!entity % p-not-stable "INCLUDE">
11 <!entity % p-stable "IGNORE">
12 <!entity % p-text "IGNORE">        <!-- define we are not a text only doc -->
13 <!entity % p-doc "INCLUDE">        <!-- and we are a formal doc           -->
14 <!entity % seealso-extra "INCLUDE"> <!-- extra stuff from seealso.sgml    -->
15 <!entity  my-copy "&copy;">        <!-- kludge for docbook2man            -->
16 ]>
17 <!--
18  File        :  $Source: /cvsroot/ijbswa/current/doc/source/developer-manual.sgml,v $
19
20  Purpose     :  developer manual
21                 This file belongs into
22                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
23
24  $Id: developer-manual.sgml,v 2.71 2016/05/27 15:24:13 fabiankeil Exp $
25
26  Copyright (C) 2001-2016 Privoxy Developers https://www.privoxy.org/
27  See LICENSE.
28
29  ========================================================================
30  NOTE: Please read developer-manual/documentation.html before touching
31  anything in this, or other Privoxy documentation. You have been warned!
32  Failure to abide by this rule will result in the revocation of your license
33  to live a peaceful existence!
34  ========================================================================
35
36 -->
37
38 <article id="index">
39   <artheader>
40     <title>Privoxy Developer Manual</title>
41     <pubdate>
42      <subscript>
43     <!-- Completely the wrong markup, but very little is allowed  -->
44     <!-- in this part of an article. FIXME -->
45       <ulink url="https://www.privoxy.org/user-manual/copyright.html">Copyright</ulink>
46       &my-copy; 2001-2016 by
47       <ulink url="https://www.privoxy.org/">Privoxy Developers</ulink>
48      </subscript>
49     </pubdate>
50
51
52     <pubdate>$Id: developer-manual.sgml,v 2.71 2016/05/27 15:24:13 fabiankeil Exp $</pubdate>
53
54 <!--
55
56 Note: this should generate a separate page, and a live link to it.
57 But it doesn't for some mysterious reason. Please leave commented
58 unless it can be fixed proper. For the time being, the copyright
59 statement will be in copyright.smgl.
60
61 Hal.
62
63 <legalnotice id="legalnotice">
64  <para>
65   text goes here ........
66  </para>
67 </legalnotice>
68
69 -->
70
71     <abstract>
72
73 <![%dummy;[
74  <para>
75  <comment>
76   This is here to keep vim syntax file from breaking :/
77   If I knew enough to fix it, I would.
78   PLEASE DO NOT REMOVE! HB: hal@foobox.net
79  </comment>
80  </para>
81  ]]>
82 <para>
83  The developer manual provides guidance on coding, testing, packaging, documentation
84  and other issues of importance to those involved with
85  <application>Privoxy</application> development. It is mandatory (and helpful!) reading
86  for anyone who wants to join the team. Note that it's currently out of date
87  and may not be entirely correct. As always, patches are welcome.
88 </para>
89
90 <!-- Include privoxy.sgml boilerplate text: -->
91
92 <!--  &p-intro; Someone interested enough in the project to contribute
93                 will already know at this point what Privoxy is. -->
94
95 <!-- end boilerplate -->
96
97 <para>
98  Please note that this document is constantly evolving. This copy represents
99  the state at the release of version &p-version;.
100  You can find the latest version of the this manual at <ulink
101  url="https://www.privoxy.org/developer-manual/">https://www.privoxy.org/developer-manual/</ulink>.
102  Please have a look at the
103  <ulink url="https://www.privoxy.org/user-manual/contact.html">contact section in the user manual</ulink>
104  if you are interested in contacting the developers.
105 </para>
106
107     </abstract>
108   </artheader>
109
110
111 <!--   ~~~~~       New section      ~~~~~     -->
112   <sect1 id="introduction"><title>Introduction</title>
113 <!--
114
115  I don't like seeing blank space :) So added *something* here.
116
117  -->
118     <para>
119      <application>Privoxy</application>, as an heir to
120      <application>Junkbuster</application>, is a Free Software project
121      and the code is licensed under the GNU General Public License version 2.
122      As such, <application>Privoxy</application> development is potentially open
123      to anyone who has the time, knowledge, and desire to contribute
124      in any capacity. Our goals are simply to continue the mission,
125      to improve <application>Privoxy</application>, and
126      to make it available to as wide an audience as possible.
127     </para>
128     <para>
129      One does not have to be a programmer to contribute. Packaging, testing,
130      documenting and porting, are all important jobs as well.
131     </para>
132
133   <!--   ~~~~~       New section      ~~~~~     -->
134   <sect2 id="quickstart"><title>Quickstart to Privoxy Development</title>
135    <para>
136     The first step is to join the <ulink
137       url="https://lists.privoxy.org/mailman/listinfo/privoxy-devel">privoxy-devel mailing list</ulink>.
138     You can submit your ideas, or even better patches. Patches are best
139     submitted to the Sourceforge tracker set up for this purpose, but
140     can be sent to the list for review too.
141    </para>
142     <para>
143      You will also need to have a cvs package installed, which will
144      entail having ssh installed as well (which seems to be a requirement of
145      SourceForge), in order to access the cvs repository. Having the GNU build
146      tools is also going to be important (particularly, autoconf and gmake).
147     </para>
148     <para>
149       For the time being (read, this section is under construction), you can
150       also refer to the extensive comments in the source code. In fact,
151       reading the code is recommended in any case.
152     </para>
153    </sect2>
154   </sect1>
155
156   <!--   ~~~~~       New section      ~~~~~     -->
157   <sect1 id="cvs"><title>The CVS Repository</title>
158     <para>
159       If you become part of the active development team, you will eventually
160       need write access to our holy grail, the CVS repository. One of the
161       team members will need to set this up for you. Please read
162       this chapter completely before accessing via CVS.
163     </para>
164
165     <sect2 id="cvsaccess"><title>Access to CVS</title>
166       <para>
167         The project's CVS repository is hosted on
168         <ulink url="https://sourceforge.net/">SourceForge.</ulink>
169         For historical reasons, the CVS server is
170         called <literal>ijbswa.cvs.sourceforge.net</literal>, the repository is
171         called <literal>ijbswa</literal>, and the source tree module is called
172         <literal>current</literal>.
173       </para>
174     </sect2>
175
176     <sect2 id="cvsbranches">
177     <title>Branches</title>
178      <para>
179        Within the CVS repository, there are modules and branches. As
180        mentioned, the sources are in the <literal>current</literal>
181        <quote>module</quote>. Other modules are present for platform specific
182        issues. There is a webview of the CVS hierarchy at <ulink
183         url="http://ijbswa.cvs.sourceforge.net/viewvc/ijbswa/"
184             >http://ijbswa.cvs.sourceforge.net/viewvc/ijbswa/</ulink>,
185        which might help with visualizing how these pieces fit together.
186      </para>
187      <!--
188      <para>
189        Branches are used to fork a sub-development path from the main trunk.
190        Within the <literal>current</literal> module where the sources are, there
191        is always at least one <quote>branch</quote> from the main trunk
192        devoted to a stable release series. The main trunk is where active
193        development takes place for the next stable series (e.g. 3.2.x).
194        So just prior to each stable series (e.g. 3.0.x), a branch is created
195        just for stable series releases (e.g. 3.0.0 -> 3.0.1 -> 3.0.2, etc).
196        Once the initial stable release of any stable branch has taken place,
197        this branch is <emphasis>only used for bugfixes</emphasis>, which have
198        had prior testing before being committed to CVS. (See <link
199        linkend="versionnumbers">Version Numbers</link> below for details on
200        versioning.)
201      </para>
202      -->
203      <para>
204       At one time there were two distinct branches: stable and unstable. The
205       more drastic changes were to be in the unstable branch. These branches
206       have now been merged to minimize time and effort of maintaining two
207       branches.
208      </para>
209     <!--
210      <para>
211        This will result in at least two active branches, which means there may
212        be occasions that require the same (or similar) item to be
213        checked into to two different places (assuming its a bugfix and needs
214        fixing in both the stable and unstable trees). This also means that in
215        order to have access to both trees, both will have to be checked out
216        separately. Use the <literal>cvs -r</literal> flag to check out a
217        branch, e.g: <literal>cvs co -r v_3_0_branch current</literal>.
218      </para>
219     -->
220     </sect2>
221
222     <sect2 id="cvscommit"><title>CVS Commit Guidelines</title>
223       <para>
224         The source tree is the heart of every software project. Every effort must
225         be made to ensure that it is readable, compilable and consistent at all
226         times. <!-- There are differing guidelines for the stable branch and the
227         main development trunk, and --> We expect anyone with CVS access to strictly
228         adhere to the following guidelines:
229       </para>
230
231       <para>
232        Basic Guidelines, for all branches:
233       </para>
234       <para>
235         <itemizedlist>
236           <listitem><para>
237             Please don't commit even
238             a small change without testing it thoroughly first. When we're
239             close to a public release, ask a fellow developer to review your
240             changes.
241           </para></listitem>
242           <listitem><para>
243             Your commit message should give a concise overview of <emphasis>what you
244             changed</emphasis> (no big details) and <emphasis>why you changed it</emphasis>
245             Just check previous messages for good examples.
246           </para></listitem>
247           <listitem><para>
248             Don't use the same message on multiple files, unless it equally applies to
249             all those files.
250           </para></listitem>
251           <listitem><para>
252             If your changes span multiple files, and the code won't recompile unless
253             all changes are committed (e.g. when changing the signature of a function),
254             then commit all files one after another, without long delays in between.
255             If necessary, prepare the commit messages in advance.
256           </para></listitem>
257           <listitem><para>
258             Before changing things on CVS, make sure that your changes are in line
259             with the team's general consensus on what should be done.
260           </para></listitem>
261           <listitem>
262            <para>
263             Note that near a major public release, we get more cautious.
264             There is always the possibility to submit a patch to the <ulink
265             url="https://sourceforge.net/tracker/?atid=311118&amp;group_id=11118&amp;func=browse">patch
266             tracker</ulink> instead.
267           </para>
268          </listitem>
269         </itemizedlist>
270       </para>
271
272 <!--
273       <para>
274        Stable branches are handled with more care, especially after the
275        initial *.*.0 release, and we are just in bugfix mode. In addition to
276        the above, the below applies only to the stable branch (currently the
277        <literal>v_3_0_branch</literal> branch):
278       </para>
279
280       <para>
281        <itemizedlist>
282         <listitem>
283          <para>
284            Do not commit <emphasis>anything</emphasis> unless your proposed
285            changes have been well tested first, preferably by other members of the
286            project, or have prior approval of the project leaders or consensus
287            of the devel list.
288          </para>
289         </listitem>
290        <listitem>
291         <para>
292          Where possible, bugfixes and changes should be tested in the main
293          development trunk first. There may be occasions where this is not
294          feasible, though.
295         </para>
296        </listitem>
297        <listitem>
298         <para>
299           Alternately, proposed changes can be submitted as patches to the patch tracker on
300           Sourceforge first: <ulink
301           url="https://sourceforge.net/tracker/?group_id=11118&#38;atid=311118">https://sourceforge.net/tracker/?group_id=11118&#38;atid=311118</ulink>.
302           Then ask for peer review.
303         </para>
304        </listitem>
305         <listitem>
306          <para>
307           Do not even think about anything except bugfixes. No new features!
308          </para>
309         </listitem>
310
311        </itemizedlist>
312       </para>
313     -->
314     </sect2>
315
316   </sect1>
317
318   <!--   ~~~~~       New section      ~~~~~     -->
319 <sect1 id="documentation"><title>Documentation Guidelines</title>
320   <para>
321     All formal documents are maintained in Docbook SGML and located in the
322     <computeroutput>doc/source/*</computeroutput> directory. You will need
323     <ulink url="http://www.docbook.org">Docbook</ulink>, the Docbook
324     DTD's and the Docbook modular stylesheets (or comparable alternatives),
325     and either <application>jade</application> or
326     <application>openjade</application> (recommended) installed in order to
327     build docs from source. Currently there is <ulink
328     url="../user-manual/index.html"><citetitle>user-manual</citetitle></ulink>,
329     <ulink url="../faq/index.html"><citetitle>FAQ</citetitle></ulink>, and, of
330     course this, the <citetitle>developer-manual</citetitle> in this format.
331     The <citetitle>README</citetitle>, <citetitle>AUTHORS</citetitle>,
332     <citetitle>INSTALL</citetitle>,
333     <citetitle>privoxy.1</citetitle> (man page), and
334     <citetitle>config</citetitle> files are also now maintained as Docbook
335     SGML. These files, when built, in the top-level source directory are
336     generated files! Also, the <application>Privoxy</application> <filename>index.html</filename> (and a
337     variation on this file, <filename>privoxy-index.html</filename>,
338     meant for inclusion with doc packages), are maintained as SGML as well.
339     <emphasis>DO NOT edit these directly</emphasis>. Edit the SGML source, or
340     contact someone involved in the documentation.
341     </para>
342     <para>
343      <filename>config</filename> requires some special handling. The reason it
344      is maintained this way is so that the extensive comments in the file
345      mirror those in <citetitle>user-manual</citetitle>. But the conversion
346      process requires going from SGML to HTML to text to special formatting
347      required for the embedded comments. Some of this does not survive so
348      well. Especially some of the examples that are longer than 80 characters.
349      The build process for this file outputs to <filename>config.new</filename>,
350      which should be reviewed for errors and mis-formatting. Once satisfied
351      that it is correct, then it should be hand copied to
352      <filename>config</filename>.
353     </para>
354     <para>
355      Other, less formal documents (e.g. <filename>LICENSE</filename>) are
356      maintained as plain text files in the top-level source directory.
357     </para>
358     <para>
359      Packagers are encouraged to include this documentation. For those without
360      the ability to build the docs locally, text versions of each are kept in
361      CVS. HTML versions are also being kept in CVS under
362      <filename>doc/webserver/*</filename>.
363     </para>
364     <para>
365      Formal documents are built with the Makefile targets of
366      <computeroutput>make dok</computeroutput>.
367      The build process uses the document SGML sources in
368      <computeroutput>doc/source/*/*</computeroutput> to update all text files in
369      <computeroutput>doc/text/</computeroutput> and to update all HTML
370      documents in <computeroutput>doc/webserver/</computeroutput>.
371     </para>
372     <para>
373      Documentation writers should please make sure documents build
374      successfully before committing to CVS, if possible.
375     </para>
376     <para>
377      How do you update the webserver (i.e. the pages on privoxy.org)?
378
379      <orderedlist numeration="arabic">
380       <listitem><para>
381         First, build the docs by running <computeroutput>make
382         dok</computeroutput>.
383       </para></listitem>
384       <listitem><para>
385         Run <computeroutput>make webserver</computeroutput> which copies all
386         files from <computeroutput>doc/webserver</computeroutput> to the
387         sourceforge webserver via scp.
388       </para></listitem>
389      </orderedlist>
390   </para>
391
392   <para>
393    Finished docs should be occasionally submitted to CVS
394    (<filename>doc/webserver/*/*.html</filename>) so that those without
395    the ability to build them locally, have access to them if needed.
396    This is especially important just prior to a new release! Please
397    do this <emphasis>after</emphasis> the <literal>$VERSION</literal> and
398    other release specific data in <filename>configure.in</filename> has been
399    updated (this is done just prior to a new release).
400   </para>
401
402 <!--   ~~~~~       New section      ~~~~~     -->
403 <sect2 id="sgml">
404 <title>Quickstart to Docbook and SGML</title>
405 <para>
406  If you are not familiar with SGML, it is a markup language similar to HTML.
407  Actually, not a mark up language per se, but a language used to define
408  markup languages. In fact, HTML is an SGML application. Both will use
409  <quote>tags</quote> to format text and other content. SGML tags can be much
410  more varied, and flexible, but do much of the same kinds of things. The tags,
411  or <quote>elements</quote>, are definable in SGML. There is no set
412  <quote>standards</quote>. Since we are using
413  <application>Docbook</application>, our tags are those that are defined by
414  <application>Docbook</application>. Much of how the finish document is
415  rendered is determined by the <quote>stylesheets</quote>.
416  The stylesheets determine how each tag gets translated to HTML, or other
417  formats.
418 </para>
419
420 <para>
421  Tags in Docbook SGML need to be always <quote>closed</quote>. If not, you
422  will likely generate errors. Example: <literal>&lt;title&gt;My
423  Title&lt;/title&gt;</literal>. They are also case-insensitive, but we
424  strongly suggest using all lower case. This keeps compatibility with
425  [Docbook] <application>XML</application>.
426 </para>
427
428 <para>
429  Our documents use <quote>sections</quote> for the most part. Sections
430  will be processed into HTML headers (e.g. <literal>h1</literal> for
431  <literal>sect1</literal>). The <application>Docbook</application> stylesheets
432  will use these to also generate the Table of Contents for each doc. Our
433  TOC's are set to a depth of three. Meaning <literal>sect1</literal>,
434  <literal>sect2</literal>, and <literal>sect3</literal> will have TOC
435  entries, but <literal>sect4</literal> will not. Each section requires
436  a <literal>&lt;title&gt;</literal> element, and at least one
437  <literal>&lt;para&gt;</literal>. There is a limit of five section
438  levels in Docbook, but generally three should be sufficient for our
439  purposes.
440 </para>
441
442 <para>
443  Some common elements that you likely will use:
444 </para>
445
446 <para>
447   <simplelist>
448     <member>
449       <emphasis>&lt;para&gt;&lt;/para&gt;</emphasis>, paragraph delimiter. Most
450       text needs to be within paragraph elements (there are some exceptions).
451     </member>
452     <member>
453       <emphasis>&lt;emphasis&gt;&lt;/emphasis&gt;</emphasis>, the stylesheets
454       make this italics.
455     </member>
456     <member>
457       <emphasis>&lt;filename&gt;&lt;/filename&gt;</emphasis>, files and directories.
458     </member>
459     <member>
460       <emphasis>&lt;command&gt;&lt;/command&gt;</emphasis>, command examples.
461     </member>
462     <member>
463       <emphasis>&lt;literallayout&gt;&lt;/literallayout&gt;</emphasis>, like
464       <literal>&lt;pre&gt;</literal>, more or less.
465     </member>
466     <member>
467       <emphasis>&lt;itemizedlist&gt;&lt;/itemizedlist&gt;</emphasis>, list with bullets.
468     </member>
469     <member>
470       <emphasis>&lt;listitem&gt;&lt;/listitem&gt;</emphasis>, member of the above.
471     </member>
472     <member>
473       <emphasis>&lt;screen&gt;&lt;/screen&gt;</emphasis>, screen output, implies
474       <literal>&lt;literallayout&gt;</literal>.
475     </member>
476     <member>
477       <emphasis>&lt;ulink url="example.com"&gt;&lt;/ulink&gt;</emphasis>, like
478       HTML <literal>&lt;a&gt;</literal> tag.
479     </member>
480     <member>
481       <emphasis>&lt;quote&gt;&lt;/quote&gt;</emphasis>, for, doh, quoting text.
482     </member>
483   </simplelist>
484 </para>
485
486 <para>
487  Look at any of the existing docs for examples of all these and more.
488 </para>
489
490 <para>
491  You might also find <quote><ulink
492  url="http://opensource.bureau-cornavin.com/crash-course/index.html">Writing Documentation
493  Using DocBook - A Crash Course</ulink></quote> useful.
494 </para>
495 </sect2>
496
497 <!--   ~~~~~       New section      ~~~~~     -->
498   <sect2 id="docstyle">
499   <title><application>Privoxy</application> Documentation Style</title>
500    <para>
501     It will be easier if everyone follows a similar writing style. This
502     just makes it easier to read what someone else has written if it
503     is all done in a similar fashion.
504    </para>
505    <para>
506     Here it is:
507    </para>
508    <para>
509     <itemizedlist>
510      <listitem>
511       <para>
512        All tags should be lower case.
513       </para>
514     </listitem>
515     <listitem>
516      <para>
517        Tags delimiting a <emphasis>block</emphasis> of text (even small
518        blocks) should be on their own line. Like:
519        <literallayout>
520  &lt;para&gt;
521   Some text goes here.
522  &lt;/para&gt;
523        </literallayout>
524        Tags marking individual words, or few words, should be in-line:
525        <literallayout>
526   Just to &lt;emphasis&gt;emphasize&lt;/emphasis&gt;, some text goes here.
527        </literallayout>
528      </para>
529    </listitem>
530    <listitem>
531     <para>
532       Tags should be nested and step indented for block text like: (except
533       in-line tags)
534      <literallayout>
535  &lt;para&gt;
536   &lt;itemizedlist&gt;
537    &lt;para&gt;
538     &lt;listitem&gt;
539       Some text goes here in our list example.
540      &lt;/listitem&gt;
541    &lt;/para&gt;
542   &lt;/itemizedlist&gt;
543  &lt;/para&gt;
544        </literallayout>
545       This makes it easier to find the text amongst the tags ;-)
546     </para>
547    </listitem>
548    <listitem>
549     <para>
550      Use white space to separate logical divisions within a document,
551      like between sections. Running everything together consistently
552      makes it harder to read and work on.
553     </para>
554    </listitem>
555    <listitem>
556     <para>
557      Do not hesitate to make comments. Comments can either use the
558      &lt;comment&gt; element, or the &lt;!--  --&gt; style comment
559      familiar from HTML. (Note in Docbook v4.x &lt;comment&gt; is
560      replaced by &lt;remark&gt;.)
561     </para>
562   </listitem>
563   <listitem>
564    <para>
565      We have an international audience. Refrain from slang, or English
566      idiosyncrasies (too many to list :). Humor also does not translate
567      well sometimes.
568    </para>
569   </listitem>
570   <listitem>
571    <para>
572     Try to keep overall line lengths in source files to 80 characters or less
573     for obvious reasons. This is not always possible, with lengthy URLs for
574     instance.
575    </para>
576   </listitem>
577   <listitem>
578    <para>
579     Our documents are available in differing formats. Right now, they
580     are just plain text and/or HTML, but others are always a
581     future possibility. Be careful with URLs (&lt;ulink&gt;), and avoid
582     this mistake:
583    </para>
584    <para>
585      My favorite site is &lt;ulink url="http://example.com"&gt;here&lt;/ulink&gt;.
586    </para>
587    <para>
588      This will render as <quote>My favorite site is here</quote>, which is
589      not real helpful in a text doc. Better like this:
590    </para>
591    <para>
592      My favorite site is &lt;ulink url="http://example.com"&gt;example.com&lt;/ulink&gt;.
593    </para>
594   </listitem>
595   <listitem>
596    <para>
597     All documents should be spell checked occasionally.
598     <application>aspell</application> can check SGML with the
599     <literal>-H</literal> option. (<application>ispell</application> I think
600     too.)
601    </para>
602   </listitem>
603
604   </itemizedlist>
605  </para>
606
607   </sect2>
608
609
610  <!--   ~~~~~       New section      ~~~~~     -->
611
612  <sect2><title>Privoxy Custom Entities</title>
613  <para>
614   <application>Privoxy</application> documentation is using
615   a number of customized <quote>entities</quote> to facilitate
616   documentation maintenance.
617  </para>
618  <para>
619   We are using a set of <quote>boilerplate</quote> files with generic text,
620   that is used by multiple docs. This way we can write something once, and use
621   it repeatedly without having to re-write the same content over and over again.
622   If editing such a file, keep in mind that it should be
623   <emphasis>generic</emphasis>. That is the purpose; so it can be used in varying
624   contexts without additional modifications.
625  </para>
626  <para>
627   We are also using what <application>Docbook</application> calls
628   <quote>internal entities</quote>. These are like variables in
629   programming. Well, sort of. For instance, we have the
630   <literal>p-version</literal> entity that contains the current
631   <application>Privoxy</application> version string. You are strongly
632   encouraged to use these where possible. Some of these obviously
633   require re-setting with each release (done by the Makefile). A sampling of
634   custom entities are listed below. See any of the main docs for examples.
635  </para>
636
637  <para>
638   <itemizedlist>
639   <listitem>
640    <para>
641     Re- <quote>boilerplate</quote> text entities are defined like:
642    </para>
643    <para>
644     <literal>&lt;!entity supported SYSTEM "supported.sgml"&gt;</literal>
645    </para>
646    <para>
647      In this example, the contents of the file,
648      <filename>supported.sgml</filename> is available for inclusion anywhere
649      in the doc. To make this happen, just reference the now defined
650      entity: <literal>&#38;supported;</literal> (starts with an ampersand
651      and ends with a semi-colon), and the contents will be dumped into
652      the finished doc at that point.
653    </para>
654   </listitem>
655   <listitem>
656    <para>
657     Commonly used <quote>internal entities</quote>:
658   </para>
659   <simplelist>
660    <member>
661     <emphasis>p-version</emphasis>: the <application>Privoxy</application>
662     version string, e.g. <quote>&p-version;</quote>.
663    </member>
664    <member>
665     <emphasis>p-status</emphasis>: the project status, either
666     <quote>alpha</quote>, <quote>beta</quote>, or <quote>stable</quote>.
667    </member>
668    <member>
669     <emphasis>p-not-stable</emphasis>: use to conditionally include
670     text in <quote>not stable</quote> releases (e.g. <quote>beta</quote>).
671    </member>
672    <member>
673     <emphasis>p-stable</emphasis>: just the opposite.
674    </member>
675    <member>
676     <emphasis>p-text</emphasis>: this doc is only generated as text.
677    </member>
678   </simplelist>
679  </listitem>
680  </itemizedlist>
681  </para>
682  <para>
683   There are others in various places that are defined for a specific
684   purpose. Read the source!
685  </para>
686
687  </sect2>
688
689  </sect1>
690
691 <!--     <listitem><para>be consistent with the redirect script (i.e. the <application>Privoxy</application> program -->
692 <!--       points via the redirect URL at sf to valid end-points in the document)</para></listitem> -->
693
694   <!--   ~~~~~       New section      ~~~~~     -->
695   <sect1 id="coding"><title>Coding Guidelines</title>
696
697     <sect2 id="s1"><title>Introduction</title>
698
699     <para>This set of standards is designed to make our lives easier.  It is
700     developed with the simple goal of helping us keep the "new and improved
701     <application>Privoxy</application>" consistent and reliable. Thus making
702     maintenance easier and increasing chances of success of the
703     project.</para>
704
705     <para>And that of course comes back to us as individuals. If we can
706     increase our development and product efficiencies then we can solve more
707     of the request for changes/improvements and in general feel good about
708     ourselves. ;-></para>
709
710   </sect2>
711
712     <sect2 id="s2"><title>Using Comments</title>
713
714
715     <sect3 id="s3"><title>Comment, Comment, Comment</title>
716
717     <para><emphasis>Explanation:</emphasis></para>
718
719     <para>Comment as much as possible without commenting the obvious.
720     For example do not comment "variable_a is equal to variable_b".
721     Instead explain why variable_a should be equal to the variable_b.
722     Just because a person can read code does not mean they will
723     understand why or what is being done. A reader may spend a lot
724     more time figuring out what is going on when a simple comment
725     or explanation would have prevented the extra research. Please
726     help your fellow Privoxy developers out!</para>
727
728     <para>The comments will also help justify the intent of the code.
729     If the comment describes something different than what the code
730     is doing then maybe a programming error is occurring.</para>
731
732     <para><emphasis>Example:</emphasis></para>
733 <programlisting>
734 /* if page size greater than 1k ... */
735 if (page_length() > 1024)
736 {
737     ... "block" the page up ...
738 }
739
740 /* if page size is small, send it in blocks */
741 if (page_length() > 1024)
742 {
743     ... "block" the page up ...
744 }
745
746 This demonstrates 2 cases of "what not to do".  The first is a
747 "syntax comment".  The second is a comment that does not fit what
748 is actually being done.
749 </programlisting>
750   </sect3>
751
752
753
754     <sect3 id="s4"><title>Use blocks for comments</title>
755
756     <para><emphasis>Explanation:</emphasis></para>
757
758     <para>Comments can help or they can clutter. They help when they
759     are differentiated from the code they describe. One line
760     comments do not offer effective separation between the comment
761     and the code. Block identifiers do, by surrounding the code
762     with a clear, definable pattern.</para>
763
764     <para><emphasis>Example:</emphasis></para>
765 <programlisting>
766 /*********************************************************************
767  * This will stand out clearly in your code!
768  *********************************************************************/
769 if (this_variable == that_variable)
770 {
771    do_something_very_important();
772 }
773
774
775 /* unfortunately, this may not */
776 if (this_variable == that_variable)
777 {
778    do_something_very_important();
779 }
780
781
782 if (this_variable == that_variable) /* this may not either */
783 {
784    do_something_very_important();
785 }</programlisting>
786
787     <para><emphasis>Exception:</emphasis></para>
788
789     <para>If you are trying to add a small logic comment and do not
790     wish to "disrupt" the flow of the code, feel free to use a 1
791     line comment which is NOT on the same line as the code.</para>
792
793
794   </sect3>
795
796
797     <sect3 id="s5"><title>Keep Comments on their own line</title>
798
799     <para><emphasis>Explanation:</emphasis></para>
800
801     <para>It goes back to the question of readability. If the comment
802     is on the same line as the code it will be harder to read than
803     the comment that is on its own line.</para>
804
805     <para>There are three exceptions to this rule, which should be
806     violated freely and often: during the definition of variables,
807     at the end of closing braces, when used to comment
808     parameters.</para>
809
810     <para><emphasis>Example:</emphasis></para>
811 <programlisting>
812 /*********************************************************************
813  * This will stand out clearly in your code,
814  * But the second example won't.
815  *********************************************************************/
816 if (this_variable == this_variable)
817 {
818    do_something_very_important();
819 }
820
821 if (this_variable == this_variable) /*can you see me?*/
822 {
823    do_something_very_important(); /*not easily*/
824 }
825
826
827 /*********************************************************************
828  * But, the encouraged exceptions:
829  *********************************************************************/
830 int urls_read     = 0;     /* # of urls read + rejected */
831 int urls_rejected = 0;     /* # of urls rejected */
832
833 if (1 == X)
834 {
835    do_something_very_important();
836 }
837
838
839 short do_something_very_important(
840    short firstparam,   /* represents something */
841    short nextparam     /* represents something else */ )
842 {
843    ...code here...
844
845 }   /* -END- do_something_very_important */
846 </programlisting>
847   </sect3>
848
849
850     <sect3 id="s6"><title>Comment each logical step</title>
851
852     <para><emphasis>Explanation:</emphasis></para>
853
854     <para>Logical steps should be commented to help others follow the
855     intent of the written code and comments will make the code more
856     readable.</para>
857
858     <para>If you have 25 lines of code without a comment, you should
859     probably go back into it to see where you forgot to put
860     one.</para>
861
862     <para>Most "for", "while", "do", etc... loops _probably_ need a
863     comment. After all, these are usually major logic
864     containers.</para>
865
866
867   </sect3>
868
869
870     <sect3 id="s7"><title>Comment All Functions Thoroughly</title>
871
872     <para><emphasis>Explanation:</emphasis></para>
873
874     <para>A reader of the code should be able to look at the comments
875     just prior to the beginning of a function and discern the
876     reason for its existence and the consequences of using it. The
877     reader should not have to read through the code to determine if
878     a given function is safe for a desired use. The proper
879     information thoroughly presented at the introduction of a
880     function not only saves time for subsequent maintenance or
881     debugging, it more importantly aids in code reuse by allowing a
882     user to determine the safety and applicability of any function
883     for the problem at hand. As a result of such benefits, all
884     functions should contain the information presented in the
885     addendum section of this document.</para>
886
887
888   </sect3>
889
890
891     <sect3 id="s8"><title>Comment at the end of braces if the
892     content is more than one screen length</title>
893
894     <para><emphasis>Explanation:</emphasis></para>
895
896     <para>Each closing brace should be followed on the same line by a
897     comment that describes the origination of the brace if the
898     original brace is off of the screen, or otherwise far away from
899     the closing brace. This will simplify the debugging,
900     maintenance, and readability of the code.</para>
901
902     <para>As a suggestion , use the following flags to make the
903     comment and its brace more readable:</para>
904
905     <para>use following a closing brace: } /* -END- if() or while ()
906     or etc... */</para>
907
908     <para><emphasis>Example:</emphasis></para>
909 <programlisting>
910 if (1 == X)
911 {
912    do_something_very_important();
913    ...some long list of commands...
914 } /* -END- if x is 1 */
915
916 or:
917
918 if (1 == X)
919 {
920    do_something_very_important();
921    ...some long list of commands...
922 } /* -END- if (1 == X) */
923 </programlisting>
924   </sect3>
925
926   </sect2>
927
928     <sect2 id="s9"><title>Naming Conventions</title>
929
930
931
932     <sect3 id="s10"><title>Variable Names</title>
933
934     <para><emphasis>Explanation:</emphasis></para>
935
936     <para>Use all lowercase, and separate words via an underscore
937     ('_'). Do not start an identifier with an underscore. (ANSI C
938     reserves these for use by the compiler and system headers.) Do
939     not use identifiers which are reserved in ANSI C++. (E.g.
940     template, class, true, false, ...). This is in case we ever
941     decide to port Privoxy to C++.</para>
942
943     <para><emphasis>Example:</emphasis></para>
944 <programlisting>
945 int ms_iis5_hack = 0;</programlisting>
946
947     <para><emphasis>Instead of:</emphasis></para>
948
949     <para>
950 <programlisting>
951 int msiis5hack = 0; int msIis5Hack = 0;
952 </programlisting>
953 </para>
954
955
956
957   </sect3>
958
959     <sect3 id="s11"><title>Function Names</title>
960
961     <para><emphasis>Explanation:</emphasis></para>
962
963     <para>Use all lowercase, and separate words via an underscore
964     ('_'). Do not start an identifier with an underscore. (ANSI C
965     reserves these for use by the compiler and system headers.) Do
966     not use identifiers which are reserved in ANSI C++. (E.g.
967     template, class, true, false, ...). This is in case we ever
968     decide to port Privoxy to C++.</para>
969
970     <para><emphasis>Example:</emphasis></para>
971 <programlisting>
972 int load_some_file(struct client_state *csp)</programlisting>
973
974     <para><emphasis>Instead of:</emphasis></para>
975
976     <para>
977 <programlisting>
978 int loadsomefile(struct client_state *csp)
979 int loadSomeFile(struct client_state *csp)
980 </programlisting>
981 </para>
982
983
984   </sect3>
985
986
987     <sect3 id="s12"><title>Header file prototypes</title>
988
989     <para><emphasis>Explanation:</emphasis></para>
990
991     <para>Use a descriptive parameter name in the function prototype
992     in header files. Use the same parameter name in the header file
993     that you use in the c file.</para>
994
995     <para><emphasis>Example:</emphasis></para>
996 <programlisting>
997 (.h) extern int load_aclfile(struct client_state *csp);
998 (.c) int load_aclfile(struct client_state *csp)</programlisting>
999
1000     <para><emphasis>Instead of:</emphasis>
1001 <programlisting>
1002 (.h) extern int load_aclfile(struct client_state *); or
1003 (.h) extern int load_aclfile();
1004 (.c) int load_aclfile(struct client_state *csp)
1005 </programlisting>
1006 </para>
1007
1008
1009   </sect3>
1010
1011
1012     <sect3 id="s13"><title>Enumerations, and #defines</title>
1013
1014     <para><emphasis>Explanation:</emphasis></para>
1015
1016     <para>Use all capital letters, with underscores between words. Do
1017     not start an identifier with an underscore. (ANSI C reserves
1018     these for use by the compiler and system headers.)</para>
1019
1020     <para><emphasis>Example:</emphasis></para>
1021 <programlisting>
1022 (enumeration) : enum Boolean {FALSE, TRUE};
1023 (#define) : #define DEFAULT_SIZE 100;</programlisting>
1024
1025     <para><emphasis>Note:</emphasis> We have a standard naming scheme for #defines
1026     that toggle a feature in the preprocessor: FEATURE_>, where
1027     > is a short (preferably 1 or 2 word) description.</para>
1028
1029     <para><emphasis>Example:</emphasis></para>
1030 <programlisting>
1031 #define FEATURE_FORCE 1
1032
1033 #ifdef FEATURE_FORCE
1034 #define FORCE_PREFIX blah
1035 #endif /* def FEATURE_FORCE */
1036 </programlisting>
1037   </sect3>
1038
1039
1040     <sect3 id="s14"><title>Constants</title>
1041
1042     <para><emphasis>Explanation:</emphasis></para>
1043
1044     <para>Spell common words out entirely (do not remove vowels).</para>
1045
1046     <para>Use only widely-known domain acronyms and abbreviations.
1047     Capitalize all letters of an acronym.</para>
1048
1049     <para>Use underscore (_) to separate adjacent acronyms and
1050     abbreviations. Never terminate a name with an underscore.</para>
1051
1052     <para><emphasis>Example:</emphasis></para>
1053 <programlisting>
1054 #define USE_IMAGE_LIST 1</programlisting>
1055
1056     <para><emphasis>Instead of:</emphasis></para>
1057
1058     <para>
1059 <programlisting>
1060 #define USE_IMG_LST 1 or
1061 #define _USE_IMAGE_LIST 1 or
1062 #define USE_IMAGE_LIST_ 1 or
1063 #define use_image_list 1 or
1064 #define UseImageList 1
1065 </programlisting>
1066 </para>
1067
1068
1069   </sect3>
1070
1071   </sect2>
1072
1073
1074     <sect2 id="s15"><title>Using Space</title>
1075
1076
1077
1078     <sect3 id="s16"><title>Put braces on a line by themselves.</title>
1079
1080     <para><emphasis>Explanation:</emphasis></para>
1081
1082     <para>The brace needs to be on a line all by itself, not at the
1083     end of the statement. Curly braces should line up with the
1084     construct that they're associated with. This practice makes it
1085     easier to identify the opening and closing braces for a
1086     block.</para>
1087
1088     <para><emphasis>Example:</emphasis></para>
1089 <programlisting>
1090 if (this == that)
1091 {
1092    ...
1093 }</programlisting>
1094
1095     <para><emphasis>Instead of:</emphasis></para>
1096
1097     <para>if (this == that) { ... }</para>
1098
1099     <para>or</para>
1100
1101     <para>if (this == that) { ... }</para>
1102
1103     <para><emphasis>Note:</emphasis> In the special case that the if-statement is
1104     inside a loop, and it is trivial, i.e. it tests for a
1105     condition that is obvious from the purpose of the block,
1106     one-liners as above may optically preserve the loop structure
1107     and make it easier to read.</para>
1108
1109     <para><emphasis>Status:</emphasis> developer-discretion.</para>
1110
1111     <para><emphasis>Example exception:</emphasis></para>
1112 <programlisting>
1113 while (more lines are read)
1114 {
1115    /* Please document what is/is not a comment line here */
1116    if (it's a comment) continue;
1117
1118    do_something(line);
1119 }
1120 </programlisting>
1121   </sect3>
1122
1123
1124     <sect3 id="s17"><title>ALL control statements should have a
1125     block</title>
1126
1127     <para><emphasis>Explanation:</emphasis></para>
1128
1129     <para>Using braces to make a block will make your code more
1130     readable and less prone to error. All control statements should
1131     have a block defined.</para>
1132
1133     <para><emphasis>Example:</emphasis></para>
1134 <programlisting>
1135 if (this == that)
1136 {
1137    do_something();
1138    do_something_else();
1139 }</programlisting>
1140
1141     <para><emphasis>Instead of:</emphasis></para>
1142
1143     <para>if (this == that) do_something(); do_something_else();</para>
1144
1145     <para>or</para>
1146
1147     <para>if (this == that) do_something();</para>
1148
1149     <para><emphasis>Note:</emphasis> The first example in "Instead of" will execute
1150     in a manner other than that which the developer desired (per
1151     indentation). Using code braces would have prevented this
1152     "feature". The "explanation" and "exception" from the point
1153     above also applies.</para>
1154
1155
1156   </sect3>
1157
1158
1159     <sect3 id="s18"><title>Do not belabor/blow-up boolean
1160     expressions</title>
1161
1162     <para><emphasis>Example:</emphasis></para>
1163 <programlisting>
1164 structure->flag = (condition);</programlisting>
1165
1166     <para><emphasis>Instead of:</emphasis></para>
1167
1168     <para>if (condition) { structure->flag = 1; } else {
1169     structure->flag = 0; }</para>
1170
1171     <para><emphasis>Note:</emphasis> The former is readable and concise. The later
1172     is wordy and inefficient. Please assume that any developer new
1173     to the project has at least a "good" knowledge of C/C++. (Hope
1174     I do not offend by that last comment ... 8-)</para>
1175
1176
1177   </sect3>
1178
1179
1180     <sect3 id="s19"><title>Use white space freely because it is
1181     free</title>
1182
1183     <para><emphasis>Explanation:</emphasis></para>
1184
1185     <para>Make it readable. The notable exception to using white space
1186     freely is listed in the next guideline.</para>
1187
1188     <para><emphasis>Example:</emphasis></para>
1189 <programlisting>
1190 int first_value   = 0;
1191 int some_value    = 0;
1192 int another_value = 0;
1193 int this_variable = 0;
1194 </programlisting>
1195   </sect3>
1196
1197
1198     <sect3 id="s20"><title>Don't use white space around structure
1199     operators</title>
1200
1201     <para><emphasis>Explanation:</emphasis></para>
1202
1203     <para>- structure pointer operator ( "->" ) - member operator (
1204     "." ) - functions and parentheses</para>
1205
1206     <para>It is a general coding practice to put pointers, references,
1207     and function parentheses next to names. With spaces, the
1208     connection between the object and variable/function name is not
1209     as clear.</para>
1210
1211     <para><emphasis>Example:</emphasis></para>
1212 <programlisting>
1213 a_struct->a_member;
1214 a_struct.a_member;
1215 function_name();</programlisting>
1216
1217     <para><emphasis>Instead of:</emphasis> a_struct -> a_member; a_struct . a_member;
1218     function_name ();</para>
1219
1220
1221   </sect3>
1222
1223
1224     <sect3 id="s21"><title>Make the last brace of a function stand
1225     out</title>
1226
1227     <para><emphasis>Example:</emphasis></para>
1228 <programlisting>
1229 int function1( ... )
1230 {
1231    ...code...
1232    return(ret_code);
1233
1234 } /* -END- function1 */
1235
1236
1237 int function2( ... )
1238 {
1239 } /* -END- function2 */
1240 </programlisting>
1241
1242     <para><emphasis>Instead of:</emphasis></para>
1243
1244     <para>int function1( ... ) { ...code... return(ret_code); } int
1245     function2( ... ) { }</para>
1246
1247     <para><emphasis>Note:</emphasis> Use 1 blank line before the closing brace and 2
1248     lines afterward. This makes the end of function standout to
1249     the most casual viewer. Although function comments help
1250     separate functions, this is still a good coding practice. In
1251     fact, I follow these rules when using blocks in "for", "while",
1252     "do" loops, and long if {} statements too. After all whitespace
1253     is free!</para>
1254
1255     <para><emphasis>Status:</emphasis> developer-discretion on the number of blank
1256     lines. Enforced is the end of function comments.</para>
1257
1258
1259   </sect3>
1260
1261
1262     <sect3 id="s22"><title>Use 3 character indentions</title>
1263
1264     <para><emphasis>Explanation:</emphasis></para>
1265
1266     <para>If some use 8 character TABs and some use 3 character TABs,
1267     the code can look *very* ragged. So use 3 character indentions
1268     only. If you like to use TABs, pass your code through a filter
1269     such as "expand -t3" before checking in your code.</para>
1270
1271     <para><emphasis>Example:</emphasis></para>
1272 <programlisting>
1273 static const char * const url_code_map[256] =
1274 {
1275    NULL, ...
1276 };
1277
1278
1279 int function1( ... )
1280 {
1281    if (1)
1282    {
1283       return ALWAYS_TRUE;
1284    }
1285    else
1286    {
1287       return HOW_DID_YOU_GET_HERE;
1288    }
1289
1290    return NEVER_GETS_HERE;
1291
1292 }
1293 </programlisting>
1294   </sect3>
1295
1296   </sect2>
1297
1298
1299     <sect2 id="s23"><title>Initializing</title>
1300
1301
1302
1303     <sect3 id="s24"><title>Initialize all variables</title>
1304
1305     <para><emphasis>Explanation:</emphasis></para>
1306
1307     <para>Do not assume that the variables declared will not be used
1308     until after they have been assigned a value somewhere else in
1309     the code. Remove the chance of accidentally using an unassigned
1310     variable.</para>
1311
1312     <para><emphasis>Example:</emphasis></para>
1313 <programlisting>
1314 short a_short = 0;
1315 float a_float  = 0;
1316 struct *ptr = NULL;</programlisting>
1317
1318     <para><emphasis>Note:</emphasis> It is much easier to debug a SIGSEGV if the
1319     message says you are trying to access memory address 00000000
1320     and not 129FA012; or array_ptr[20] causes a SIGSEV vs.
1321     array_ptr[0].</para>
1322
1323     <para><emphasis>Status:</emphasis> developer-discretion if and only if the
1324     variable is assigned a value "shortly after" declaration.</para>
1325
1326   </sect3>
1327   </sect2>
1328
1329
1330     <sect2 id="s25"><title>Functions</title>
1331
1332
1333
1334     <sect3 id="s26"><title>Name functions that return a boolean as a
1335     question.</title>
1336
1337     <para><emphasis>Explanation:</emphasis></para>
1338
1339     <para>Value should be phrased as a question that would logically
1340     be answered as a true or false statement</para>
1341
1342     <para><emphasis>Example:</emphasis></para>
1343 <programlisting>
1344 should_we_block_this();
1345 contains_an_image();
1346 is_web_page_blank();
1347 </programlisting>
1348   </sect3>
1349
1350
1351     <sect3 id="s27"><title>Always specify a return type for a
1352     function.</title>
1353
1354     <para><emphasis>Explanation:</emphasis></para>
1355
1356     <para>The default return for a function is an int. To avoid
1357     ambiguity, create a return for a function when the return has a
1358     purpose, and create a void return type if the function does not
1359     need to return anything.</para>
1360
1361
1362   </sect3>
1363
1364
1365     <sect3 id="s28"><title>Minimize function calls when iterating by
1366     using variables</title>
1367
1368     <para><emphasis>Explanation:</emphasis></para>
1369
1370     <para>It is easy to write the following code, and a clear argument
1371     can be made that the code is easy to understand:</para>
1372
1373     <para><emphasis>Example:</emphasis></para>
1374 <programlisting>
1375 for (size_t cnt = 0; cnt &lt; block_list_length(); cnt++)
1376 {
1377    ....
1378 }</programlisting>
1379
1380     <para><emphasis>Note:</emphasis> Unfortunately, this makes a function call for
1381     each and every iteration. This increases the overhead in the
1382     program, because the compiler has to look up the function each
1383     time, call it, and return a value. Depending on what occurs in
1384     the block_list_length() call, it might even be creating and
1385     destroying structures with each iteration, even though in each
1386     case it is comparing "cnt" to the same value, over and over.
1387     Remember too - even a call to block_list_length() is a function
1388     call, with the same overhead.</para>
1389
1390     <para>Instead of using a function call during the iterations,
1391     assign the value to a variable, and evaluate using the
1392     variable.</para>
1393
1394     <para><emphasis>Example:</emphasis></para>
1395 <programlisting>
1396 size_t len = block_list_length();
1397
1398 for (size_t cnt = 0; cnt &lt; len; cnt++)
1399 {
1400    ....
1401 }</programlisting>
1402
1403     <para><emphasis>Exceptions:</emphasis> if the value of block_list_length()
1404     *may* change or could *potentially* change, then you must code the
1405     function call in the for/while loop.</para>
1406
1407
1408   </sect3>
1409
1410
1411     <sect3 id="s29"><title>Pass and Return by Const Reference</title>
1412
1413     <para><emphasis>Explanation:</emphasis></para>
1414
1415     <para>This allows a developer to define a const pointer and call
1416     your function. If your function does not have the const
1417     keyword, we may not be able to use your function. Consider
1418     strcmp, if it were defined as: extern int strcmp(char *s1,
1419     char *s2);</para>
1420
1421     <para>I could then not use it to compare argv's in main: int
1422     main(int argc, const char *argv[]) { strcmp(argv[0], "privoxy");
1423      }</para>
1424
1425     <para>Both these pointers are *const*! If the c runtime library
1426     maintainers do it, we should too.</para>
1427
1428
1429   </sect3>
1430
1431
1432     <sect3 id="s30"><title>Pass and Return by Value</title>
1433
1434     <para><emphasis>Explanation:</emphasis></para>
1435
1436     <para>Most structures cannot fit onto a normal stack entry (i.e.
1437     they are not 4 bytes or less). Aka, a function declaration
1438     like: int load_aclfile(struct client_state csp)</para>
1439
1440     <para>would not work. So, to be consistent, we should declare all
1441     prototypes with "pass by value": int load_aclfile(struct
1442     client_state *csp)</para>
1443
1444
1445   </sect3>
1446
1447
1448     <sect3 id="s31"><title>Names of include files</title>
1449
1450     <para><emphasis>Explanation:</emphasis></para>
1451
1452     <para>Your include statements should contain the file name without
1453     a path. The path should be listed in the Makefile, using -I as
1454     processor directive to search the indicated paths. An exception
1455     to this would be for some proprietary software that utilizes a
1456     partial path to distinguish their header files from system or
1457     other header files.</para>
1458
1459     <para><emphasis>Example:</emphasis></para>
1460 <programlisting>
1461 #include &lt;iostream.h&gt;     /* This is not a local include */
1462 #include "config.h"       /* This IS a local include */
1463 </programlisting>
1464
1465     <para><emphasis>Exception:</emphasis></para>
1466
1467     <para>
1468 <programlisting>
1469 /* This is not a local include, but requires a path element. */
1470 #include &lt;sys/fileName.h&gt;
1471 </programlisting>
1472 </para>
1473
1474     <para><emphasis>Note:</emphasis> Please! do not add "-I." to the Makefile
1475     without a _very_ good reason. This duplicates the #include
1476     "file.h" behavior.</para>
1477
1478
1479   </sect3>
1480
1481
1482     <sect3 id="s32"><title>Provide multiple inclusion
1483     protection</title>
1484
1485     <para><emphasis>Explanation:</emphasis></para>
1486
1487     <para>Prevents compiler and linker errors resulting from
1488     redefinition of items.</para>
1489
1490     <para>Wrap each header file with the following syntax to prevent
1491     multiple inclusions of the file. Of course, replace PROJECT_H
1492     with your file name, with "." Changed to "_", and make it
1493     uppercase.</para>
1494
1495     <para><emphasis>Example:</emphasis></para>
1496 <programlisting>
1497 #ifndef PROJECT_H_INCLUDED
1498 #define PROJECT_H_INCLUDED
1499  ...
1500 #endif /* ndef PROJECT_H_INCLUDED */
1501 </programlisting>
1502   </sect3>
1503
1504
1505     <sect3 id="s33"><title>Use `extern "C"` when appropriate</title>
1506
1507     <para><emphasis>Explanation:</emphasis></para>
1508
1509     <para>If our headers are included from C++, they must declare our
1510     functions as `extern "C"`. This has no cost in C, but increases
1511     the potential re-usability of our code.</para>
1512
1513     <para><emphasis>Example:</emphasis></para>
1514 <programlisting>
1515 #ifdef __cplusplus
1516 extern "C"
1517 {
1518 #endif /* def __cplusplus */
1519
1520 ... function definitions here ...
1521
1522 #ifdef __cplusplus
1523 }
1524 #endif /* def __cplusplus */
1525 </programlisting>
1526   </sect3>
1527
1528
1529     <sect3 id="s34"><title>Where Possible, Use Forward Struct
1530     Declaration Instead of Includes</title>
1531
1532     <para><emphasis>Explanation:</emphasis></para>
1533
1534     <para>Useful in headers that include pointers to other struct's.
1535     Modifications to excess header files may cause needless
1536     compiles.</para>
1537
1538     <para><emphasis>Example:</emphasis></para>
1539 <programlisting>
1540 /*********************************************************************
1541  * We're avoiding an include statement here!
1542  *********************************************************************/
1543 struct file_list;
1544 extern file_list *xyz;</programlisting>
1545
1546     <para><emphasis>Note:</emphasis> If you declare "file_list xyz;" (without the
1547     pointer), then including the proper header file is necessary.
1548     If you only want to prototype a pointer, however, the header
1549     file is unnecessary.</para>
1550
1551     <para><emphasis>Status:</emphasis> Use with discretion.</para>
1552
1553
1554   </sect3>
1555   </sect2>
1556
1557     <sect2 id="s35"><title>General Coding Practices</title>
1558
1559
1560
1561     <sect3 id="s36"><title>Turn on warnings</title>
1562
1563     <para><emphasis>Explanation</emphasis></para>
1564
1565     <para>Compiler warnings are meant to help you find bugs. You
1566     should turn on as many as possible. With GCC, the switch is
1567     "-Wall". Try and fix as many warnings as possible.</para>
1568
1569
1570   </sect3>
1571
1572
1573     <sect3 id="s37"><title>Provide a default case for all switch
1574     statements</title>
1575
1576     <para><emphasis>Explanation:</emphasis></para>
1577
1578     <para>What you think is guaranteed is never really guaranteed. The
1579     value that you don't think you need to check is the one that
1580     someday will be passed. So, to protect yourself from the
1581     unknown, always have a default step in a switch statement.</para>
1582
1583     <para><emphasis>Example:</emphasis></para>
1584 <programlisting>
1585 switch (hash_string(cmd))
1586 {
1587    case hash_actions_file:
1588       ... code ...
1589       break;
1590
1591    case hash_confdir:
1592       ... code ...
1593       break;
1594
1595    default:
1596       log_error( ... );
1597       ... anomaly code goes here ...
1598       continue; / break; / exit( 1 ); / etc ...
1599
1600 } /* end switch (hash_string(cmd)) */</programlisting>
1601
1602     <para><emphasis>Note:</emphasis> If you already have a default condition, you
1603     are obviously exempt from this point. Of note, most of the
1604     WIN32 code calls `DefWindowProc' after the switch statement.
1605     This API call *should* be included in a default statement.</para>
1606
1607     <para><emphasis>Another Note:</emphasis> This is not so much a readability issue
1608     as a robust programming issue. The "anomaly code goes here" may
1609     be no more than a print to the STDERR stream (as in
1610     load_config). Or it may really be an abort condition.</para>
1611
1612     <para><emphasis>Status:</emphasis> Programmer discretion is advised.</para>
1613
1614
1615   </sect3>
1616
1617
1618     <sect3 id="s38"><title>Try to avoid falling through cases in a
1619     switch statement.</title>
1620
1621     <para><emphasis>Explanation:</emphasis></para>
1622
1623     <para>In general, you will want to have a 'break' statement within
1624     each 'case' of a switch statement. This allows for the code to
1625     be more readable and understandable, and furthermore can
1626     prevent unwanted surprises if someone else later gets creative
1627     and moves the code around.</para>
1628
1629     <para>The language allows you to plan the fall through from one
1630     case statement to another simply by omitting the break
1631     statement within the case statement. This feature does have
1632     benefits, but should only be used in rare cases. In general,
1633     use a break statement for each case statement.</para>
1634
1635     <para>If you choose to allow fall through, you should comment both
1636     the fact of the fall through and reason why you felt it was
1637     necessary.</para>
1638
1639
1640   </sect3>
1641
1642
1643     <sect3 id="s40"><title>Don't mix size_t and other types</title>
1644
1645     <para><emphasis>Explanation:</emphasis></para>
1646
1647     <para>The type of size_t varies across platforms. Do not make
1648     assumptions about whether it is signed or unsigned, or about
1649     how long it is. Do not compare a size_t against another
1650     variable of a different type (or even against a constant)
1651     without casting one of the values.</para>
1652
1653
1654   </sect3>
1655
1656
1657     <sect3 id="s41"><title>Declare each variable and struct on its
1658     own line.</title>
1659
1660     <para><emphasis>Explanation:</emphasis></para>
1661
1662     <para>It can be tempting to declare a series of variables all on
1663     one line. Don't.</para>
1664
1665     <para><emphasis>Example:</emphasis></para>
1666 <programlisting>
1667 long a = 0;
1668 long b = 0;
1669 long c = 0;</programlisting>
1670
1671     <para><emphasis>Instead of:</emphasis></para>
1672
1673     <para>long a, b, c;</para>
1674
1675     <para><emphasis>Explanation:</emphasis> - there is more room for comments on the
1676     individual variables - easier to add new variables without
1677     messing up the original ones - when searching on a variable to
1678     find its type, there is less clutter to "visually"
1679     eliminate</para>
1680
1681     <para><emphasis>Exceptions:</emphasis> when you want to declare a bunch of loop
1682     variables or other trivial variables; feel free to declare them
1683     on one line. You should, although, provide a good comment on
1684     their functions.</para>
1685
1686     <para><emphasis>Status:</emphasis> developer-discretion.</para>
1687
1688
1689   </sect3>
1690
1691
1692     <sect3 id="s42"><title>Use malloc/zalloc sparingly</title>
1693
1694     <para><emphasis>Explanation:</emphasis></para>
1695
1696     <para>Create a local struct (on the stack) if the variable will
1697     live and die within the context of one function call.</para>
1698
1699     <para>Only "malloc" a struct (on the heap) if the variable's life
1700     will extend beyond the context of one function call.</para>
1701
1702     <para><emphasis>Example:</emphasis></para>
1703 <programlisting>
1704 If a function creates a struct and stores a pointer to it in a
1705 list, then it should definitely be allocated via `malloc'.
1706 </programlisting>
1707   </sect3>
1708
1709
1710     <sect3 id="s43"><title>The Programmer Who Uses 'malloc' is
1711     Responsible for Ensuring 'free'</title>
1712
1713     <para><emphasis>Explanation:</emphasis></para>
1714
1715     <para>If you have to "malloc" an instance, you are responsible for
1716     insuring that the instance is `free'd, even if the deallocation
1717     event falls within some other programmer's code. You are also
1718     responsible for ensuring that deletion is timely (i.e. not too
1719     soon, not too late). This is known as "low-coupling" and is a
1720     "good thing (tm)". You may need to offer a
1721     free/unload/destructor type function to accommodate this.</para>
1722
1723     <para><emphasis>Example:</emphasis></para>
1724 <programlisting>
1725 int load_re_filterfile(struct client_state *csp) { ... }
1726 static void unload_re_filterfile(void *f) { ... }</programlisting>
1727
1728     <para><emphasis>Exceptions:</emphasis></para>
1729
1730     <para>The developer cannot be expected to provide `free'ing
1731     functions for C run-time library functions ... such as
1732     `strdup'.</para>
1733
1734     <para><emphasis>Status:</emphasis> developer-discretion. The "main" use of this
1735     standard is for allocating and freeing data structures (complex
1736     or nested).</para>
1737
1738
1739   </sect3>
1740
1741
1742     <sect3 id="s44"><title>Add loaders to the `file_list' structure
1743     and in order</title>
1744
1745     <para><emphasis>Explanation:</emphasis></para>
1746
1747     <para>I have ordered all of the "blocker" file code to be in alpha
1748     order. It is easier to add/read new blockers when you expect a
1749     certain order.</para>
1750
1751     <para><emphasis>Note:</emphasis> It may appear that the alpha order is broken in
1752     places by POPUP tests coming before PCRS tests. But since
1753     POPUPs can also be referred to as KILLPOPUPs, it is clear that
1754     it should come first.</para>
1755
1756
1757   </sect3>
1758
1759
1760     <sect3 id="s45"><title>"Uncertain" new code and/or changes to
1761     existing code, use XXX</title>
1762
1763     <para><emphasis>Explanation:</emphasis></para>
1764
1765     <para>If you have enough confidence in new code or confidence in
1766     your changes, but are not *quite* sure of the repercussions,
1767     add this:</para>
1768
1769     <para>/* XXX: this code has a logic error on platform XYZ, *
1770     attempting to fix */ #ifdef PLATFORM ...changed code here...
1771     #endif</para>
1772
1773     <para>or:</para>
1774
1775     <para>/* XXX: I think the original author really meant this...
1776     */ ...changed code here...</para>
1777
1778     <para>or:</para>
1779
1780     <para>/* XXX: new code that *may* break something else... */
1781     ...new code here...</para>
1782
1783     <para><emphasis>Note:</emphasis> If you make it clear that this may or may not
1784     be a "good thing (tm)", it will be easier to identify and
1785     include in the project (or conversely exclude from the
1786     project).</para>
1787
1788
1789   </sect3>
1790
1791   </sect2>
1792
1793     <sect2 id="s46"><title>Addendum: Template for files and function
1794     comment blocks:</title>
1795
1796     <para><emphasis>Example for file comments:</emphasis></para>
1797 <programlisting>
1798 const char FILENAME_rcs[] = "$I&lt;!-- Break CVS Substitution -->d$";
1799 /*********************************************************************
1800  *
1801  * File        :  $S&lt;!-- Break CVS Substitution -->ource$
1802  *
1803  * Purpose     :  (Fill me in with a good description!)
1804  *
1805  * Copyright   :  Written by and Copyright (C) 2001-2009
1806  *                the Privoxy team. https://www.privoxy.org/
1807  *
1808  *                This program is free software; you can redistribute it
1809  *                and/or modify it under the terms of the GNU General
1810  *                Public License as published by the Free Software
1811  *                Foundation; either version 2 of the License, or (at
1812  *                your option) any later version.
1813  *
1814  *                This program is distributed in the hope that it will
1815  *                be useful, but WITHOUT ANY WARRANTY; without even the
1816  *                implied warranty of MERCHANTABILITY or FITNESS FOR A
1817  *                PARTICULAR PURPOSE.  See the GNU General Public
1818  *                License for more details.
1819  *
1820  *                The GNU General Public License should be included with
1821  *                this file.  If not, you can view it at
1822  *                http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1823  *                or write to the Free Software Foundation, Inc.,
1824  *                51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1825  *                USA
1826  *
1827  *********************************************************************/
1828
1829
1830 #include "config.h"
1831
1832    ...necessary include files for us to do our work...
1833
1834 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1835 </programlisting>
1836
1837     <para><emphasis>Note:</emphasis> This declares the rcs variables that should be
1838     added to the "show-proxy-args" page. If this is a brand new
1839     creation by you, you are free to change the "Copyright" section
1840     to represent the rights you wish to maintain.</para>
1841
1842     <para><emphasis>Note:</emphasis> The formfeed character that is present right
1843     after the comment flower box is handy for (X|GNU)Emacs users to
1844     skip the verbiage and get to the heart of the code (via
1845     `forward-page' and `backward-page'). Please include it if you
1846     can.</para>
1847
1848     <para><emphasis>Example for file header comments:</emphasis></para>
1849 <programlisting>
1850 #ifndef _FILENAME_H
1851 #define _FILENAME_H
1852 #define FILENAME_H_VERSION "$I&lt;!-- Break CVS Substitution -->d$"
1853 /*********************************************************************
1854  *
1855  * File        :  $S&lt;!-- Break CVS Substitution -->ource$
1856  *
1857  * Purpose     :  (Fill me in with a good description!)
1858  *
1859  * Copyright   :  Written by and Copyright (C) 2001-2009
1860  *                the Privoxy team. https://www.privoxy.org/
1861  *
1862  *                This program is free software; you can redistribute it
1863  *                and/or modify it under the terms of the GNU General
1864  *                Public License as published by the Free Software
1865  *                Foundation; either version 2 of the License, or (at
1866  *                your option) any later version.
1867  *
1868  *                This program is distributed in the hope that it will
1869  *                be useful, but WITHOUT ANY WARRANTY; without even the
1870  *                implied warranty of MERCHANTABILITY or FITNESS FOR A
1871  *                PARTICULAR PURPOSE.  See the GNU General Public
1872  *                License for more details.
1873  *
1874  *                The GNU General Public License should be included with
1875  *                this file.  If not, you can view it at
1876  *                http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1877  *                or write to the Free Software Foundation, Inc.,
1878  *                51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1879  *                USA
1880  *
1881  *********************************************************************/
1882
1883
1884 #include "project.h"
1885
1886 #ifdef __cplusplus
1887 extern "C" {
1888 #endif
1889
1890    ... function headers here ...
1891
1892
1893 /* Revision control strings from this header and associated .c file */
1894 extern const char FILENAME_rcs[];
1895 extern const char FILENAME_h_rcs[];
1896
1897
1898 #ifdef __cplusplus
1899 } /* extern "C" */
1900 #endif
1901
1902 #endif /* ndef _FILENAME_H */
1903
1904 /*
1905   Local Variables:
1906   tab-width: 3
1907   end:
1908 */
1909 </programlisting>
1910
1911     <para><emphasis>Example for function comments:</emphasis></para>
1912 <programlisting>
1913 /*********************************************************************
1914  *
1915  * Function    :  FUNCTION_NAME
1916  *
1917  * Description :  (Fill me in with a good description!)
1918  *
1919  * parameters  :
1920  *          1  :  param1 = pointer to an important thing
1921  *          2  :  x      = pointer to something else
1922  *
1923  * Returns     :  0 => Ok, everything else is an error.
1924  *
1925  *********************************************************************/
1926 int FUNCTION_NAME(void *param1, const char *x)
1927 {
1928    ...
1929    return 0;
1930
1931 }
1932 </programlisting>
1933
1934     <para><emphasis>Note:</emphasis> If we all follow this practice, we should be
1935     able to parse our code to create a "self-documenting" web
1936     page.</para>
1937
1938   </sect2>
1939
1940   </sect1>
1941
1942   <!--   ~~~~~       New section      ~~~~~     -->
1943   <sect1 id="testing"><title>Testing Guidelines</title>
1944     <para>To be filled.
1945 </para>
1946
1947     <!--   ~~~~~       New section      ~~~~~     -->
1948     <sect2 id="testing-plan"><title>Testplan for releases</title>
1949       <para>
1950        Explain release numbers. major, minor. developer releases. etc.
1951
1952 <orderedlist numeration="arabic">
1953           <listitem><para>
1954 Remove any existing rpm with rpm -e
1955 </para></listitem>
1956           <listitem><para>
1957 Remove any file that was left over. This includes (but is not limited to)
1958       <itemizedlist>
1959                 <listitem><para>/var/log/privoxy</para></listitem>
1960                 <listitem><para>/etc/privoxy</para></listitem>
1961                 <listitem><para>/usr/sbin/privoxy</para></listitem>
1962                 <listitem><para>/etc/init.d/privoxy</para></listitem>
1963                 <listitem><para>/usr/doc/privoxy*</para></listitem>
1964               </itemizedlist>
1965 </para></listitem>
1966           <listitem><para>
1967 Install the rpm. Any error messages?
1968 </para></listitem>
1969           <listitem><para>start,stop,status <application>Privoxy</application> with the specific script
1970       (e.g. /etc/rc.d/init/privoxy stop). Reboot your machine. Does
1971       autostart work?</para></listitem>
1972           <listitem><para>Start browsing. Does <application>Privoxy</application> work? Logfile written?</para></listitem>
1973           <listitem><para>Remove the rpm. Any error messages? All files removed?</para></listitem>
1974         </orderedlist>
1975 </para>
1976     </sect2>
1977     <!-- XXX: Document how to write test reports and where to send them -->
1978   </sect1>
1979
1980   <!--   ~~~~~       New section      ~~~~~     -->
1981   <sect1 id="newrelease"><title>Releasing a New Version</title>
1982     <para>
1983         When we release versions of <application>Privoxy</application>,
1984         our work leaves our cozy secret lab and has to work in the cold
1985         RealWorld[tm]. Once it is released, there is no way to call it
1986         back, so it is very important that great care is taken to ensure
1987         that everything runs fine, and not to introduce problems in the
1988         very last minute.
1989     </para>
1990     <para>
1991         So when releasing a new version, please adhere exactly to the
1992         procedure outlined in this chapter.
1993     </para>
1994
1995     <para>
1996         The following programs are required to follow this process:
1997         <filename>ncftpput</filename> (ncftp), <filename>scp, ssh</filename> (ssh),
1998         <filename>gmake</filename> (GNU's version of make), autoconf, cvs.
1999     </para>
2000
2001     <sect2 id="versionnumbers">
2002     <title>Version numbers</title>
2003
2004     <para>
2005       First you need to determine which version number the release will have.
2006       <application>Privoxy</application> version numbers consist of three numbers,
2007       separated by dots, like in X.Y.Z (e.g. 3.0.0), where:
2008         <itemizedlist>
2009           <listitem>
2010             <para>
2011               X, the version major, is rarely ever changed. It is increased by one if
2012               turning a development branch into stable substantially changes the functionality,
2013               user interface or configuration syntax. Majors 1 and 2 were
2014               <application>Junkbuster</application>, and 3 will be the first stable
2015               <application>Privoxy</application> release.
2016             </para>
2017           </listitem>
2018           <listitem>
2019             <para>
2020               Y, the version minor, represents the branch within the major version.
2021               At any point in time, there are two branches being maintained:
2022               The stable branch, with an even minor, say, 2N, in which no functionality is
2023               being added and only bug-fixes are made, and 2N+1, the development branch, in
2024               which the further development of <application>Privoxy</application> takes
2025               place.
2026               This enables us to turn the code upside down and inside out, while at the same time
2027               providing and maintaining a stable version.
2028               The minor is reset to zero (and one) when the major is incremented. When a development
2029               branch has matured to the point where it can be turned into stable, the old stable branch
2030               2N is given up (i.e. no longer maintained), the former development branch 2N+1 becomes the
2031               new stable branch 2N+2, and a new development branch 2N+3 is opened.
2032             </para>
2033           </listitem>
2034           <listitem>
2035             <para>
2036               Z, the point or sub version, represents a release of the software within a branch.
2037               It is therefore incremented immediately before each code freeze.
2038               In development branches, only the even point versions correspond to actual releases,
2039               while the odd ones denote the evolving state of the sources on CVS in between.
2040               It follows that Z is odd on CVS in development branches most of the time. There, it gets
2041               increased to an even number immediately before a code freeze, and is increased to an odd
2042               number again immediately thereafter.
2043               This ensures that builds from CVS snapshots are easily distinguished from released versions.
2044               The point version is reset to zero when the minor changes.
2045             </para>
2046             <para>
2047               Stable branches work a little differently, since there should be
2048               little to no development happening in such branches. Remember,
2049               only bugfixes, which presumably should have had some testing
2050               before being committed. Stable branches will then have their
2051               version reported as <literal>0.0.0</literal>, during that period
2052               between releases when changes are being added. This is to denote
2053               that this code is <emphasis>not for release</emphasis>. Then
2054               as the release nears, the version is bumped according: e.g.
2055               <literal>3.0.1 -> 0.0.0 -> 3.0.2</literal>.
2056             </para>
2057           </listitem>
2058         </itemizedlist>
2059     </para>
2060     <para>
2061      In summary, the main CVS trunk is the development branch where new
2062      features are being worked on for the next stable series. This should
2063      almost always be where the most activity takes place. There is always at
2064      least one stable branch from the trunk, e.g now it is
2065      <literal>3.0</literal>, which is only used to release stable versions.
2066      Once the initial *.0 release of the stable branch has been done, then as a
2067      rule, only bugfixes that have had prior testing should be committed to
2068      the stable branch. Once there are enough bugfixes to justify a new
2069      release, the version of this branch is again incremented Example: 3.0.0
2070      -> 3.0.1 -> 3.0.2, etc are all stable releases from within the stable
2071      branch. 3.1.x is currently the main trunk, and where work on 3.2.x is
2072      taking place. If any questions, please post to the devel list
2073      <emphasis>before</emphasis> committing to a stable branch!
2074     </para>
2075     <para>
2076      Developers should remember too that if they commit a bugfix to the stable
2077      branch, this will more than likely require a separate submission to the
2078      main trunk, since these are separate development trees within CVS. If you
2079      are working on both, then this would require at least two separate check
2080      outs (i.e main trunk, <emphasis>and</emphasis> the stable release branch,
2081      which is <literal>v_3_0_branch</literal> at the moment).
2082     </para>
2083
2084     </sect2>
2085
2086     <sect2 id="beforerelease">
2087     <title>Before the Release: Freeze</title>
2088      <para>
2089        The following <emphasis>must be done by one of the
2090        developers</emphasis> prior to each new release.
2091      </para>
2092      <para>
2093       <itemizedlist>
2094        <listitem>
2095         <para>
2096          Make sure that everybody who has worked on the code in the last
2097          couple of days has had a chance to yell <quote>no!</quote> in case
2098          they have pending changes/fixes in their pipelines. Announce the
2099          freeze so that nobody will interfere with last minute changes.
2100         </para>
2101       </listitem>
2102       <listitem>
2103        <para>
2104          Increment the version number (point from odd to even in development
2105          branches!) in <filename>configure.in</filename>. (RPM spec files
2106          will need to be incremented as well.)
2107        </para>
2108       </listitem>
2109       <listitem>
2110        <para>
2111         If <filename>default.action</filename> has changed since last
2112         release (i.e. software release or standalone actions file release),
2113         bump up its version info to A.B in this line:
2114        </para>
2115        <para>
2116         <programlisting>
2117   {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
2118 </programlisting>
2119        </para>
2120        <para>
2121         Then change the version info in doc/webserver/actions/index.php,
2122         line: '$required_actions_file_version = "A.B";'
2123        </para>
2124       </listitem>
2125       <listitem>
2126        <para>
2127         All documentation should be rebuild after the version bump.
2128         Finished docs should be then be committed to CVS (for those
2129         without the ability to build these). Some docs may require
2130         rather obscure processing tools. <filename>config</filename>,
2131         the man page (and the html version of the man page)
2132         fall in this category. REAMDE, the man page, AUTHORS, and config
2133         should all also be committed to CVS for other packagers. The
2134         formal docs should be uploaded to the webserver. See the
2135         Section "Updating the webserver" in this manual for details.
2136        </para>
2137       </listitem>
2138       <listitem>
2139        <para>
2140          The <citetitle>User Manual</citetitle> is also used for context
2141          sensitive help for the CGI editor. This is version sensitive, so that
2142          the user will get appropriate help for his/her release. So with
2143          each release a fresh version should be uploaded to the webserver
2144          (this is in addition to the main <citetitle>User Manual</citetitle>
2145          link from the main page since we need to keep manuals for various
2146          versions available). The CGI pages will link to something like
2147          <literal>http://privoxy.org/$(VERSION)/user-manual/</literal>. This
2148          will need to be updated for each new release. There is no Makefile
2149          target for this at this time!!! It needs to be done manually.
2150        </para>
2151       </listitem>
2152       <listitem>
2153        <para>
2154         All developers should look at the <filename>ChangeLog</filename> and
2155         make sure noteworthy changes are referenced.
2156        </para>
2157      </listitem>
2158       <listitem>
2159        <para>
2160         <emphasis>Commit all files that were changed in the above steps!</emphasis>
2161        </para>
2162       </listitem>
2163       <listitem>
2164        <para>
2165         Tag all files in CVS with the version number with
2166         <quote><command>cvs tag v_X_Y_Z</command></quote>.
2167         Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
2168        </para>
2169       </listitem>
2170      <listitem>
2171        <para>
2172         If the release was in a development branch, increase the point version
2173         from even to odd (X.Y.(Z+1)) again in <filename>configure.in</filename> and
2174         commit your change.
2175        </para>
2176       </listitem>
2177      <listitem>
2178        <para>
2179         On the webserver, copy the user manual to a new top-level directory
2180         called <filename>X.Y.Z</filename>. This ensures that help links from the CGI
2181         pages, which have the version as a prefix, will go into the right version of the manual.
2182         If this is a development branch release, also symlink <filename>X.Y.(Z-1)</filename>
2183         to <filename>X.Y.Z</filename> and <filename>X.Y.(Z+1)</filename> to
2184         <filename>.</filename> (i.e. dot).
2185        </para>
2186       </listitem>
2187       </itemizedlist>
2188      </para>
2189     </sect2>
2190
2191     <sect2 id="therelease">
2192     <title>Building and Releasing the Packages</title>
2193      <para>
2194       Now the individual packages can be built and released. Note that for
2195       GPL reasons the first package to be released is always the source tarball.
2196      </para>
2197
2198      <para>
2199       For <emphasis>all</emphasis> types of packages, including the source tarball,
2200       <emphasis>you must make sure that you build from clean sources by exporting
2201       the right version from CVS into an empty directory</emphasis> (just press return when
2202       asked for a password):
2203      </para>
2204
2205      <para>
2206       <programlisting>
2207   mkdir dist # delete or choose different name if it already exists
2208   cd dist
2209   cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
2210   cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
2211 </programlisting>
2212     </para>
2213
2214     <para>
2215      <emphasis>Do NOT change</emphasis> a single bit, including, but not limited to
2216      version information after export from CVS. This is to make sure that
2217      all release packages, and with them, all future bug reports, are based
2218      on exactly the same code.
2219     </para>
2220
2221     <warning>
2222      <para>
2223       Every significant release of Privoxy has included at least one
2224       package that either had incorrect versions of files, missing files,
2225       or incidental leftovers from a previous build process that gave
2226       unknown numbers of users headaches to try to figure out what was
2227       wrong. PLEASE, make sure you are using pristene sources, and are
2228       following the prescribed process!
2229      </para>
2230     </warning>
2231
2232     <para>
2233      Please find additional instructions for the source tarball and the
2234      individual platform dependent binary packages below. And details
2235      on the Sourceforge release process below that.
2236     </para>
2237
2238     <sect3 id="pack-guidelines">
2239     <title>Note on Privoxy Packaging</title>
2240      <para>
2241       Please keep these general guidelines in mind when putting together
2242       your package. These apply to <emphasis>all</emphasis> platforms!
2243      </para>
2244      <para>
2245       <itemizedlist>
2246        <listitem>
2247         <para>
2248           <application>Privoxy</application> <emphasis>requires</emphasis>
2249           write access to: all <filename>*.action</filename> files, all
2250           logfiles, and the <filename>trust</filename> file. You will
2251           need to determine the best way to do this for your platform.
2252         </para>
2253        </listitem>
2254        <listitem>
2255         <para>
2256           Please include up to date documentation. At a bare minimum:
2257         </para>
2258         <simplelist>
2259          <member>
2260           <filename>LICENSE</filename> (top-level directory)
2261          </member>
2262         </simplelist>
2263         <simplelist>
2264          <member>
2265           <filename>README</filename> (top-level directory)
2266          </member>
2267         </simplelist>
2268         <simplelist>
2269          <member>
2270           <filename>AUTHORS</filename> (top-level directory)
2271          </member>
2272         </simplelist>
2273         <simplelist>
2274          <member>
2275           <filename>man page</filename> (top-level directory, Unix-like
2276           platforms only)
2277          </member>
2278         </simplelist>
2279         <simplelist>
2280          <member>
2281           <filename>The User Manual</filename> (doc/webserver/user-manual/)
2282          </member>
2283         </simplelist>
2284         <simplelist>
2285          <member>
2286           <filename>FAQ</filename> (doc/webserver/faq/)
2287          </member>
2288         </simplelist>
2289         <para>
2290           Also suggested: <filename>Developer Manual</filename>
2291           (doc/webserver/developer-manual) and <filename>ChangeLog</filename>
2292           (top-level directory). <filename>FAQ</filename> and the manuals are
2293           HTML docs. There are also text versions in
2294           <filename>doc/text/</filename> which could conceivably also be
2295           included.
2296         </para>
2297         <para>
2298          The documentation has been designed such that the manuals are linked
2299          to each other from parallel directories, and should be packaged
2300          that way. <filename>privoxy-index.html</filename> can also be
2301          included and can serve as a focal point for docs and other links of
2302          interest (and possibly renamed to <filename>index.html</filename>).
2303          This should be one level up from the manuals. There is a link also
2304          on this page to an HTMLized version of the man page. To avoid 404 for
2305          this, it is in CVS as
2306          <filename>doc/webserver/man-page/privoxy-man-page.html</filename>,
2307          and should be included along with the manuals. There is also a
2308          css stylesheets that can be included for better presentation:
2309          <filename>p_doc.css</filename>. This should be in the same directory
2310          with <filename>privoxy-index.html</filename>, (i.e. one level up from
2311          the manual directories).
2312         </para>
2313       </listitem>
2314       <listitem>
2315        <para>
2316         <filename>user.action</filename> and <filename>user.filter</filename>
2317         are designed for local preferences. Make sure these do not get overwritten!
2318         <filename>config</filename> should not be overwritten either. This
2319         has especially important configuration data in it.
2320         <filename>trust</filename> should be left in tact as well.
2321        </para>
2322       </listitem>
2323       <listitem>
2324        <para>
2325         Other configuration files (<filename>default.action</filename> and
2326         <filename>default.filter</filename>) should be installed as the new
2327         defaults, but all previously installed configuration files should be
2328         preserved as backups. This is just good manners :-) These files are
2329         likely to change between releases and contain important new features
2330         and bug fixes.
2331        </para>
2332      </listitem>
2333      <listitem>
2334       <para>
2335        Please check platform specific notes in this doc, if you haven't
2336        done <quote>Privoxy</quote> packaging before for other platform
2337        specific issues. Conversely, please add any notes that you know
2338        are important for your platform (or contact one of the doc
2339        maintainers to do this if you can't).
2340       </para>
2341     </listitem>
2342     <listitem>
2343      <para>
2344        Packagers should do a <quote>clean</quote> install of their
2345        package after building it. So any previous installs should be
2346        removed first to ensure the integrity of the newly built package.
2347        Then run the package for a while to make sure there are no
2348        obvious problems, before uploading.
2349      </para>
2350     </listitem>
2351
2352       </itemizedlist>
2353      </para>
2354
2355     </sect3>
2356
2357     <sect3 id="newrelease-tarball"><title>Source Tarball</title>
2358       <para>
2359         First, <emphasis>make sure that you have freshly exported the right
2360         version into an empty directory</emphasis>. (See "Building and releasing
2361         packages" above). Then run:
2362       </para>
2363       <para>
2364         <programlisting>
2365   cd current
2366   autoheader && autoconf && ./configure
2367 </programlisting>
2368       </para>
2369       <para>
2370         Then do:
2371       </para>
2372       <para>
2373         <programlisting>
2374   make tarball-dist
2375 </programlisting>
2376       </para>
2377       <para>
2378         To upload the package to Sourceforge, simply issue
2379       </para>
2380       <para>
2381         <programlisting>
2382   make tarball-upload
2383 </programlisting>
2384       </para>
2385       <para>
2386         Go to the displayed URL and release the file publicly on Sourceforge.
2387         For the change log field, use the relevant section of the
2388         <filename>ChangeLog</filename> file.
2389       </para>
2390     </sect3>
2391
2392     <sect3 id="newrelease-rpm"><title>SuSE, Conectiva or Red Hat RPM</title>
2393       <para>
2394         In following text, replace <replaceable class="parameter">dist</replaceable>
2395         with either <quote>rh</quote> for Red Hat or <quote>suse</quote> for SuSE.
2396       </para>
2397       <para>
2398         First, <emphasis>make sure that you have freshly exported the right
2399         version into an empty directory</emphasis>. (See "Building and releasing
2400         packages" above).
2401       </para>
2402       <para>
2403         As the only exception to not changing anything after export from CVS,
2404         now examine the file <filename>privoxy-</filename><replaceable class="parameter">dist</replaceable><filename>.spec</filename>
2405         and make sure that the version information and the RPM release number are
2406         correct. The RPM release numbers for each version start at one. Hence it must
2407         be reset to one if this is the first RPM for
2408         <replaceable class="parameter">dist</replaceable> which is built from version
2409         X.Y.Z. Check the
2410         <ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">file
2411         list</ulink> if unsure. Else, it must be set to the highest already available RPM
2412         release number for that version plus one.
2413       </para>
2414       <para>
2415         Then run:
2416       </para>
2417       <para>
2418         <programlisting>
2419   cd current
2420   autoheader && autoconf && ./configure
2421 </programlisting>
2422       </para>
2423       <para>
2424         Then do
2425       </para>
2426       <para>
2427         <programlisting>
2428   make <replaceable class="parameter">dist</replaceable>-dist
2429 </programlisting>
2430       </para>
2431       <para>
2432         To upload the package to Sourceforge, simply issue
2433       </para>
2434       <para>
2435         <programlisting>
2436   make <replaceable class="parameter">dist</replaceable>-upload <replaceable class="parameter">rpm_packagerev</replaceable>
2437 </programlisting>
2438       </para>
2439       <para>
2440         where <replaceable class="parameter">rpm_packagerev</replaceable> is the
2441         RPM release number as determined above.
2442         Go to the displayed URL and release the file publicly on Sourceforge.
2443         Use the release notes and change log from the source tarball package.
2444       </para>
2445     </sect3>
2446
2447     <sect3 id="newrelease-os2"><title>OS/2</title>
2448       <para>
2449         First, <emphasis>make sure that you have freshly exported the right
2450         version into an empty directory</emphasis>. (See "Building and releasing
2451         packages" above). Then get the OS/2 Setup module:
2452       </para>
2453       <para>
2454         <programlisting>
2455   cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup
2456 </programlisting>
2457       </para>
2458       <para>
2459         You will need a mix of development tools.
2460         The main compilation takes place with IBM Visual Age C++.
2461         Some ancillary work takes place with GNU tools, available from
2462         various sources like hobbes.nmsu.edu.
2463         Specificially, you will need <filename>autoheader</filename>,
2464         <filename>autoconf</filename> and <filename>sh</filename> tools.
2465         The packaging takes place with WarpIN, available from various sources, including
2466         its home page: <ulink url="http://www.xworkplace.org/">xworkplace</ulink>.
2467       </para>
2468       <para>
2469         Change directory to the <filename>os2setup</filename> directory.
2470         Edit the os2build.cmd file to set the final executable filename.
2471         For example,
2472       </para>
2473       <para>
2474         <programlisting>
2475   installExeName='privoxyos2_setup_X.Y.Z.exe'
2476 </programlisting>
2477       </para>
2478       <para>
2479         Next, edit the <filename>IJB.wis</filename> file so the release number matches
2480         in the <filename>PACKAGEID</filename> section:
2481       </para>
2482       <para>
2483         <programlisting>
2484   PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
2485 </programlisting>
2486       </para>
2487       <para>
2488         You're now ready to build.  Run:
2489       </para>
2490       <para>
2491         <programlisting>
2492   os2build
2493 </programlisting>
2494       </para>
2495       <para>
2496          You will find the  WarpIN-installable executable in the
2497         <filename>./files</filename> directory. Upload this anonymously to
2498          <filename>uploads.sourceforge.net/incoming</filename>, create a release
2499          for it, and you're done. Use the release notes and Change Log from the
2500          source tarball package.
2501       </para>
2502     </sect3>
2503
2504     <sect3 id="newrelease-solaris"><title>Solaris</title>
2505       <para>
2506         Login to Sourceforge's compilefarm via ssh:
2507       </para>
2508       <para>
2509         <programlisting>
2510   ssh cf.sourceforge.net
2511 </programlisting>
2512       </para>
2513       <para>
2514         Choose the right operating system (not the Debian one).
2515         When logged in, <emphasis>make sure that you have freshly exported the right
2516         version into an empty directory</emphasis>. (See "Building and releasing
2517         packages" above). Then run:
2518       </para>
2519       <para>
2520         <programlisting>
2521   cd current
2522   autoheader && autoconf && ./configure
2523 </programlisting>
2524       </para>
2525       <para>
2526         Then run
2527       </para>
2528       <para>
2529         <programlisting>
2530   gmake solaris-dist
2531 </programlisting>
2532       </para>
2533       <para>
2534         which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2535         solaris-upload</command> on the Sourceforge machine (no ncftpput). You now have
2536         to manually upload the archive to Sourceforge's ftp server and release
2537         the file publicly. Use the release notes and Change Log from the
2538         source tarball package.
2539       </para>
2540     </sect3>
2541
2542     <sect3 id="newrelease-windows"><title>Windows</title>
2543       <para>
2544         Use the <ulink url="http://www.fruitbat.org/Cygwin/index.html#cygwincirca">
2545         Cygwin Time Machine</ulink> to install the last 1.5 version of Cygwin.
2546         Run the following commands from within the Cygwin 1.5 bash shell.
2547       </para>
2548       <para>
2549         First, <emphasis>make sure that you have freshly exported the right
2550         version into an empty directory</emphasis>. (See "Building and releasing
2551         packages" above). Then get the Windows setup module:
2552       </para>
2553       <para>
2554       <programlisting>
2555   cvs -z3  -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup
2556 </programlisting>
2557       </para>
2558       <para>
2559         Then you can build the package.  This is fully automated, and is
2560         controlled by <filename>winsetup/GNUmakefile</filename>.
2561         All you need to do is:
2562       </para>
2563       <para>
2564       <programlisting>
2565   cd winsetup
2566   make
2567 </programlisting>
2568       </para>
2569       <para>
2570         Now you can manually rename <filename>privoxy_setup.exe</filename> to
2571         <filename>privoxy_setup_X_Y_Z.exe</filename>, and upload it to
2572         SourceForge. When releasing the package on SourceForge, use the release notes
2573         and Change Log from the source tarball package.
2574       </para>
2575     </sect3>
2576
2577     <sect3 id="newrelease-debian"><title>Debian</title>
2578       <para>
2579         First, <emphasis>make sure that you have freshly exported the
2580         right version into an empty directory</emphasis>. (See
2581         "Building and releasing packages" above).  Then add a log
2582         entry to <filename>debian/changelog</filename>, if it is not
2583         already there, for example by running:
2584       </para>
2585       <para>
2586         <programlisting>
2587   debchange -v &p-version;-&p-status;-1 "New upstream version"
2588 </programlisting>
2589       </para>
2590       <para>
2591         Then, run:
2592       </para>
2593       <para>
2594         <programlisting>
2595   dpkg-buildpackage -rfakeroot -us -uc -b
2596 </programlisting>
2597       </para>
2598       <para>
2599         This will create
2600         <filename>../privoxy_&p-version;-&p-status;-1_i386.deb</filename>
2601         which can be uploaded.  To upload the package to Sourceforge, simply
2602         issue
2603       </para>
2604       <para>
2605         <programlisting>
2606   make debian-upload
2607 </programlisting>
2608       </para>
2609     </sect3>
2610
2611     <sect3 id="newrelease-macosx"><title>Mac OS X</title>
2612       <para>
2613         First, <emphasis>make sure that you have freshly exported the right
2614         version into an empty directory</emphasis>. (See "Building and releasing
2615         packages" above).
2616       </para>
2617       <para>
2618         There are three modules available in the CVS repository for use on Mac
2619         OS X, though technically only two of them generate a release (the other
2620         can be used to install from source).
2621       </para>
2622       <sect4 id="OS-X-OSXPackageBuilder-module">
2623       <title>OSXPackageBuilder module</title>
2624         <para>
2625           The OSXPackageBuilder module generates OS X installer packages
2626           supporting all Macs running OS X 10.4 and above. Obtain it from CVS as
2627           follows into a folder parallel to the exported privoxy source:
2628           <programlisting>
2629   cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co OSXPackageBuilder
2630 </programlisting>
2631         </para>
2632         <para>
2633           The module contains complete instructions on its usage in the file
2634           <filename>OS X Package Builder HOWTO.txt</filename>.
2635         </para>
2636         <para>
2637           Once the package(s) have been generated, you can then upload them
2638           directly to the Files section of the Sourceforge project in the
2639           Macintosh (OS X) folder. Each new version release of Privoxy should
2640           have a new subfolder created in which to store its files. Please
2641           ensure that the folder contains a readme file that makes it clear
2642           which package is for whichversion of OS X.
2643         </para>
2644       </sect4>
2645       <sect4 id="OS-X-osxsetup-module">
2646       <title>osxsetup module (DEPRECATED)</title>
2647         <para>
2648           <emphasis>This module is deprecated since the installer it generates
2649           places all Privoxy files in one folder in a non-standard location, and
2650           supports only Intel Macs running OS X 10.6 or higher.</emphasis>
2651         </para>
2652         <para>
2653           Check out the module from CVS as follows into a folder parallel to the
2654           exported privoxy source:
2655           <programlisting>
2656   cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup
2657 </programlisting>
2658         </para>
2659         <para>
2660           Then run:
2661         </para>
2662         <para>
2663           <programlisting>
2664   cd osxsetup
2665   build
2666 </programlisting>
2667         </para>
2668         <para>
2669           This will run <filename>autoheader</filename>, <filename>autoconf</filename>
2670           and <filename>configure</filename> as well as <filename>make</filename>.
2671           Finally, it will copy over the necessary files to the ./osxsetup/files
2672           directory for further processing by <filename>PackageMaker</filename>.
2673         </para>
2674         <para>
2675         Bring up PackageMaker with the PrivoxyPackage.pmsp definition file,
2676         modify the package name to match the release, and hit the "Create
2677         package" button. If you specify ./Privoxy.pkg as the output package
2678         name, you can then create the distributable zip file with the command:
2679         </para>
2680         <para>
2681           <programlisting>
2682   zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
2683 </programlisting>
2684         </para>
2685         <para>
2686           You can then upload this file directly to the Files section of the
2687           Sourceforge project in the Macintosh (OS X) folder. Each new version
2688           release of Privoxy should have a new subfolder created in which to
2689           store its files.
2690           Please ensure that the folder contains a readme file that makes it
2691           clear which version(s) of OS X the package supports.
2692         </para>
2693       </sect4>
2694       <sect4 id="OS-X-macsetup-module">
2695       <title>macsetup module</title>
2696         <para>
2697           The macsetup module is ideal if you wish to build and install Privoxy
2698           from source on a single machine.
2699         </para>
2700         <para>
2701           Check out the module from CVS as follows into a folder parallel to the
2702           exported privoxy source:
2703           <programlisting>
2704   cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co macsetup
2705 </programlisting>
2706         </para>
2707         <para>
2708           The module contains complete instructions on its usage in its
2709           <filename>README</filename> file. The end result will be the
2710           exported version of Privoxy installed on the build machine.
2711         </para>
2712       </sect4>
2713     </sect3>
2714
2715     <sect3 id="newrelease-freebsd"><title>FreeBSD</title>
2716       <para>
2717         Update the www/privoxy port and submit a diff upstream.
2718         For details see the <ulink url="https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/">FreeBSD Porter's Handbook</ulink>.
2719       </para>
2720     </sect3>
2721    </sect2>
2722
2723    <sect2 id="releasing">
2724    <title>Uploading and Releasing Your Package</title>
2725     <para>
2726       After the package is ready, it is time to upload it
2727       to SourceForge, and go through the release steps. The upload
2728       is done via FTP:
2729     </para>
2730      <para>
2731       <itemizedlist>
2732        <listitem>
2733         <para>
2734           Upload to: <ulink url="ftp://upload.sourceforge.net/incoming">ftp://upload.sourceforge.net/incoming</ulink>
2735         </para>
2736       </listitem>
2737       <listitem>
2738        <para>
2739          user: <literal>anonymous</literal>
2740        </para>
2741       </listitem>
2742       <listitem>
2743        <para>
2744          password: <literal>ijbswa-developers@lists.sourceforge.net</literal>
2745        </para>
2746       </listitem>
2747      </itemizedlist>
2748     </para>
2749     <para>
2750      Or use the <command>make</command> targets as described above.
2751     </para>
2752     <para>
2753      Once this done go to <ulink
2754       url="https://sourceforge.net/project/admin/editpackages.php?group_id=11118"
2755       >https://sourceforge.net/project/admin/editpackages.php?group_id=11118</ulink>,
2756      making sure you are logged in. Find your target platform in the
2757      second column, and click <literal>Add Release</literal>. You will
2758      then need to create a new release for your package, using the format
2759      of <literal>$VERSION ($CODE_STATUS)</literal>, e.g. <emphasis>&p-version;
2760      (beta)</emphasis>.
2761     </para>
2762     <para>
2763      Now just follow the prompts. Be sure to add any appropriate Release
2764      notes. You should see your freshly uploaded packages in
2765      <quote>Step 2. Add Files To This Release</quote>. Check the
2766      appropriate box(es). Remember at each step to hit the
2767      <quote>Refresh/Submit</quote> buttons! You should now see your
2768      file(s) listed in Step 3. Fill out the forms with the appropriate
2769      information for your platform, being sure to hit <quote>Update</quote>
2770      for each file. If anyone is monitoring your platform, check the
2771      <quote>email</quote> box at the very bottom to notify them of
2772      the new package. This should do it!
2773     </para>
2774     <para>
2775      If you have made errors, or need to make changes, you can go through
2776      essentially the same steps, but select <literal>Edit Release</literal>,
2777      instead of <literal>Add Release</literal>.
2778     </para>
2779    </sect2>
2780
2781     <sect2 id="afterrelease">
2782     <title>After the Release</title>
2783      <para>
2784       When all (or: most of the) packages have been uploaded and made available,
2785       send an email to the <ulink url="mailto:privoxy-announce@lists.privoxy.org">announce
2786       mailing list</ulink>, Subject: "Version X.Y.Z available for download". Be sure to
2787       include the
2788       <ulink url="https://sourceforge.net/project/showfiles.php?group_id=11118">download
2789       location</ulink>, the release notes and the Changelog. Also, post an
2790       updated News item on the project page Sourceforge, and update the Home
2791       page and docs linked from the Home page (see below). Other news sites
2792       and release oriented sites, such as Freshmeat, should also be notified.
2793      </para>
2794    </sect2>
2795
2796   </sect1>
2797
2798   <!--   ~~~~~       New section      ~~~~~     -->
2799   <sect1 id="webserver-update"><title>Update the Webserver</title>
2800    <para>
2801     The webserver should be updated at least with each stable release. When
2802     updating, please follow these steps to make sure that no broken links,
2803     inconsistent contents or permission problems will occur (as it has many
2804     times in the past!):
2805    </para>
2806    <para>
2807     If you have changed anything in the stable-branch documentation source
2808     SGML files, do:
2809    </para>
2810    <para>
2811     <programlisting>
2812   make dok
2813 </programlisting>
2814    </para>
2815    <para>
2816     That will generate <filename>doc/webserver/user-manual</filename>,
2817     <filename>doc/webserver/developer-manual</filename>,
2818     <filename>doc/webserver/faq</filename>,
2819     <filename>doc/webserver/index.html</filename> automatically.
2820    </para>
2821    <para>
2822     If you changed the manual page sources, generate
2823     <filename>doc/webserver/man-page/privoxy-man-page.html</filename>
2824     by running <quote><command>make man</command></quote>. (This is
2825     a separate target due to dependencies on some obscure perl scripts
2826     [now in CVS, but not well tested]. See comments in <filename>GNUmakefile</filename>.)
2827    </para>
2828    <para>
2829     If you want to add new files to the webserver, create them locally in
2830     the <filename>doc/webserver/*</filename> directory (or
2831     create new directories under <filename>doc/webserver</filename>).
2832    </para>
2833    <para>
2834     Next, commit any changes from the above steps to CVS. All set?
2835     If these are docs in the stable branch, then do:
2836    </para>
2837    <para>
2838     <programlisting>
2839   make webserver
2840 </programlisting>
2841    </para>
2842    <para>
2843     This will do the upload to <ulink url="https://www.privoxy.org/">the
2844     webserver</ulink> (www.privoxy.org) and ensure all files and directories
2845     there are group writable.
2846    </para>
2847    <para>
2848     Please do <emphasis>NOT</emphasis> use any other means of transferring
2849     files to the webserver to avoid permission problems. Also, please do not
2850     upload docs from development branches or versions. The publicly posted
2851     docs should be in sync with the last official release.
2852    </para>
2853   </sect1>
2854
2855   <!--
2856
2857   This program is free software; you can redistribute it
2858   and/or modify it under the terms of the GNU General
2859   Public License as published by the Free Software
2860   Foundation; either version 2 of the License, or (at
2861   your option) any later version.
2862
2863   This program is distributed in the hope that it will
2864   be useful, but WITHOUT ANY WARRANTY; without even the
2865   implied warranty of MERCHANTABILITY or FITNESS FOR A
2866   PARTICULAR PURPOSE.  See the GNU General Public
2867   License for more details.
2868
2869   The GNU General Public License should be included with
2870   this file.  If not, you can view it at
2871   http://www.gnu.org/copyleft/gpl.html
2872   or write to the Free Software Foundation, Inc., 59
2873   Temple Place - Suite 330, Boston, MA  02111-1307, USA.
2874
2875   -->
2876
2877 </article>