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