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