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