fd1e65bb089f5624f29c8f1e39fc99406d041e0f
[privoxy.git] / doc / source / developer-manual.sgml
1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
2 <!--
3  File        :  $Source: /cvsroot/ijbswa/current/doc/source/developer-manual.sgml,v $
4
5  Purpose     :  developer manual
6                 This file belongs into
7                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
8                 
9  $Id: developer-manual.sgml,v 1.14 2002/03/30 19:04:08 swa Exp $
10
11  Written by and Copyright (C) 2001 the SourceForge
12  Privoxy team. http://www.privoxy.org/
13
14  Based on the Internet Junkbuster originally written
15  by and Copyright (C) 1997 Anonymous Coders and 
16  Junkbusters Corporation.  http://www.junkbusters.com
17 -->
18
19 <article id="index">
20   <artheader>
21     <title>Privoxy Developer Manual</title>
22
23     <pubdate>$Id: developer-manual.sgml,v 1.14 2002/03/30 19:04:08 swa Exp $</pubdate>
24
25     <authorgroup>
26       <author>
27         <affiliation>
28           <orgname>By: Privoxy Developers</orgname>
29         </affiliation>
30       </author>
31     </authorgroup>
32
33     <abstract>
34       <para>
35  The developer manual gives the users information on how to help the developer
36  team. It provides guidance on coding, testing, documentation and other
37  issues. 
38  </para>
39
40 <para>
41  <application>Privoxy</application> is a web proxy with advanced filtering
42  capabilities for protecting privacy, filtering web page content, managing
43  cookies, controlling access, and removing ads, banners, pop-ups and other
44  obnoxious Internet junk. <application>Privoxy</application> has a very
45  flexible configuration and can be customized to suit individual needs and
46  tastes. <application>Privoxy</application> has application for both
47  stand-alone systems and multi-user networks.
48 </para>
49
50 <para>
51  <application>Privoxy</application> is based on the code of the 
52  <application>Internet Junkbuster</application>.
53  <application>Junkbuster</application> was originally written by JunkBusters
54  Corporation, and was released as free open-source software under the GNU GPL.
55  Stefan Waldherr made many improvements, and started the SourceForge project
56  to continue development. Other developers have since joined Stefan.
57 </para>
58
59 <para>
60  You can find the latest version of the user manual at <ulink
61  url="http://www.privoxy.org/developer-manual/">http://www.privoxy.org/developer-manual/</ulink>.
62  Please see the Contact section in the user-manual if you want to contact the
63  developers.
64 </para>
65
66 <!--        <para> -->
67 <!--    Feel free to send a note to the developers at <email>ijbswa-developers@lists.sourceforge.net</email>. -->
68 <!--   </para> -->
69
70     </abstract>
71   </artheader>
72
73   <!--   ~~~~~       New section      ~~~~~     -->
74   <sect1 id="introduction"><title>Introduction</title>
75     <para>To be filled.
76 </para>
77   </sect1>
78
79   <!--   ~~~~~       New section      ~~~~~     -->
80   <sect1 id="quickstart"><title>Quickstart to Privoxy Development</title>
81     <para>
82 You'll need an account on Sourceforge to support our development. Mail you ID
83 to the list and wait until a project manager has added you.
84
85 For the time beeing (read, this section is under construction), please note the
86 following guidelines for changing stuff in the code. If it is
87         <orderedlist numeration="arabic">
88                 <listitem><para>
89                 A bugfix / clean-up / cosmetic thing: shoot
90                 </para></listitem>
91                 <listitem><para>
92                 A new feature that can be turned off: shoot
93                 </para></listitem>
94                 <listitem><para>
95                 A clear improvement w/o side effects on other parts of the code: shoot
96                 </para></listitem>
97                 <listitem><para>
98                 A matter of taste: ask the list
99                 </para></listitem>
100                 <listitem><para>
101                 A major redesign of some part of the code: ask the list
102                 </para></listitem>
103         </orderedlist>  
104 </para>         
105   </sect1>      
106         
107   <!--   ~~~~~       New section      ~~~~~     -->
108   <sect1 id="documentation"><title>Documentation Guidelines</title>
109     <para>
110         All docs are in SGML format and located in the <computeroutput>doc/source</computeroutput> directory.
111         </para>
112         <para>
113         How do you update the webserver (i.e. the pages on sourceforge)?
114         <orderedlist numeration="arabic">
115                 <listitem><para>
116         Run <computeroutput>make dok</computeroutput> (which uses the documents in <computeroutput>doc/source</computeroutput> to update all
117         text files in <computeroutput>doc/text</computeroutput> and to update
118 all web documents in <computeroutput>doc/webserver</computeroutput>.
119                 </para></listitem>
120                 <listitem><para>
121         Run <computeroutput>make webserver</computeroutput> which copies all files from
122 <computeroutput>doc/webserver</computeroutput> to the sourceforge webserver
123 via scp.
124                 </para></listitem>
125         </orderedlist>
126   </para>
127  </sect1>
128
129 <!--     <listitem><para>be consistent with the redirect script (i.e. the <application>Privoxy</application> program -->
130 <!--       points via the redirect URL at sf to valid end-points in the document)</para></listitem> -->
131
132   <!--   ~~~~~       New section      ~~~~~     -->
133   <sect1 id="coding"><title>Coding Guidelines</title>
134
135     <sect2 id="s1"><title>Introduction</title>
136
137     <para>This set of standards is designed to make our lives easier.  It is
138     developed with the simple goal of helping us keep the "new and improved
139     <application>Privoxy</application>" consistent and reliable. Thus making
140     maintenance easier and increasing chances of success of the
141     project.</para>
142
143     <para>And that of course comes back to us as individuals. If we can
144     increase our development and product efficiencies then we can solve more
145     of the request for changes/improvements and in general feel good about
146     ourselves. ;-></para>
147
148   </sect2>
149
150     <sect2 id="s2"><title>Using Comments</title>
151  
152
153     <sect3 id="s3"><title>Comment, Comment, Comment</title>
154
155     <para><emphasis>Explanation:</emphasis></para>
156
157     <para>Comment as much as possible without commenting the obvious.
158     For example do not comment "aVariable is equal to bVariable".
159     Instead explain why aVariable should be equal to the bVariable.
160     Just because a person can read code does not mean they will
161     understand why or what is being done. A reader may spend a lot
162     more time figuring out what is going on when a simple comment
163     or explanation would have prevented the extra research. Please
164     help your brother IJB'ers out!</para>
165
166     <para>The comments will also help justify the intent of the code.
167     If the comment describes something different than what the code
168     is doing then maybe a programming error is occurring.</para>
169
170     <para><emphasis>Example:</emphasis></para>
171 <programlisting>
172 /* if page size greater than 1k ... */
173 if ( PageLength() > 1024 )
174 {
175     ... "block" the page up ...
176 }
177
178 /* if page size is small, send it in blocks */
179 if ( PageLength() > 1024 )
180 {
181     ... "block" the page up ...
182 }
183
184 This demonstrates 2 cases of "what not to do".  The first is a
185 "syntax comment".  The second is a comment that does not fit what
186 is actually being done.
187 </programlisting>
188   </sect3>
189
190     
191
192     <sect3 id="s4"><title>Use blocks for comments</title>
193
194     <para><emphasis>Explanation:</emphasis></para>
195
196     <para>Comments can help or they can clutter. They help when they
197     are differentiated from the code they describe. One line
198     comments do not offer effective separation between the comment
199     and the code. Block identifiers do, by surrounding the code
200     with a clear, definable pattern.</para>
201
202     <para><emphasis>Example:</emphasis></para>
203 <programlisting>
204 /*********************************************************************
205  * This will stand out clearly in your code!
206  *********************************************************************/
207 if ( thisVariable == thatVariable )
208 {
209    DoSomethingVeryImportant();
210 }
211
212
213 /* unfortunately, this may not */
214 if ( thisVariable == thatVariable )
215 {
216    DoSomethingVeryImportant();
217 }
218
219
220 if ( thisVariable == thatVariable ) /* this may not either */
221 {
222    DoSomethingVeryImportant();
223 }</programlisting>
224
225     <para><emphasis>Exception:</emphasis></para>
226
227     <para>If you are trying to add a small logic comment and do not
228     wish to "disrubt" the flow of the code, feel free to use a 1
229     line comment which is NOT on the same line as the code.</para>
230
231     
232   </sect3>
233     
234
235     <sect3 id="s5"><title>Keep Comments on their own line</title>
236
237     <para><emphasis>Explanation:</emphasis></para>
238
239     <para>It goes back to the question of readability. If the comment
240     is on the same line as the code it will be harder to read than
241     the comment that is on its own line.</para>
242
243     <para>There are three exceptions to this rule, which should be
244     violated freely and often: during the definition of variables,
245     at the end of closing braces, when used to comment
246     parameters.</para>
247
248     <para><emphasis>Example:</emphasis></para>
249 <programlisting>
250 /*********************************************************************
251  * This will stand out clearly in your code,
252  * But the second example won't.
253  *********************************************************************/
254 if ( thisVariable == thatVariable )
255 {
256    DoSomethingVeryImportant();
257 }
258
259 if ( thisVariable == thatVariable ) /*can you see me?*/
260 {
261    DoSomethingVeryImportant(); /*not easily*/
262 }
263
264
265 /*********************************************************************
266  * But, the encouraged exceptions:
267  *********************************************************************/
268 int urls_read     = 0;     /* # of urls read + rejected */
269 int urls_rejected = 0;     /* # of urls rejected */
270
271 if ( 1 == X )
272 {
273    DoSomethingVeryImportant();
274 }
275
276
277 short DoSomethingVeryImportant(
278    short firstparam,   /* represents something */
279    short nextparam     /* represents something else */ )
280 {
281    ...code here...
282
283 }   /* -END- DoSomethingVeryImportant */
284 </programlisting>
285   </sect3>
286     
287
288     <sect3 id="s6"><title>Comment each logical step</title>
289
290     <para><emphasis>Explanation:</emphasis></para>
291
292     <para>Logical steps should be commented to help others follow the
293     intent of the written code and comments will make the code more
294     readable.</para>
295
296     <para>If you have 25 lines of code without a comment, you should
297     probably go back into it to see where you forgot to put
298     one.</para>
299
300     <para>Most "for", "while", "do", etc... loops _probably_ need a
301     comment. After all, these are usually major logic
302     containers.</para>
303
304     
305   </sect3>
306     
307
308     <sect3 id="s7"><title>Comment All Functions Thoroughly</title>
309
310     <para><emphasis>Explanation:</emphasis></para>
311
312     <para>A reader of the code should be able to look at the comments
313     just prior to the beginning of a function and discern the
314     reason for its existence and the consequences of using it. The
315     reader should not have to read through the code to determine if
316     a given function is safe for a desired use. The proper
317     information thoroughly presented at the introduction of a
318     function not only saves time for subsequent maintenance or
319     debugging, it more importantly aids in code reuse by allowing a
320     user to determine the safety and applicability of any function
321     for the problem at hand. As a result of such benefits, all
322     functions should contain the information presented in the
323     addendum section of this document.</para>
324
325     
326   </sect3>
327     
328
329     <sect3 id="s8"><title>Comment at the end of braces if the
330     content is more than one screen length</title>
331
332     <para><emphasis>Explanation:</emphasis></para>
333
334     <para>Each closing brace should be followed on the same line by a
335     comment that describes the origination of the brace if the
336     original brace is off of the screen, or otherwise far away from
337     the closing brace. This will simplify the debugging,
338     maintenance, and readability of the code.</para>
339
340     <para>As a suggestion , use the following flags to make the
341     comment and its brace more readable:</para>
342
343     <para>use following a closing brace: } /* -END- if() or while ()
344     or etc... */</para>
345
346     <para><emphasis>Example:</emphasis></para>
347 <programlisting>
348 if ( 1 == X )
349 {
350    DoSomethingVeryImportant();
351    ...some long list of commands...
352 } /* -END- if x is 1 */
353
354 or:
355
356 if ( 1 == X )
357 {
358    DoSomethingVeryImportant();
359    ...some long list of commands...
360 } /* -END- if ( 1 == X ) */
361 </programlisting>
362   </sect3>
363     
364   </sect2>
365
366     <sect2 id="s9"><title>Naming Conventions</title>
367
368     
369
370     <sect3 id="s10"><title>Variable Names</title>
371
372     <para><emphasis>Explanation:</emphasis></para>
373
374     <para>Use all lowercase, and seperate words via an underscore
375     ('_'). Do not start an identifier with an underscore. (ANSI C
376     reserves these for use by the compiler and system headers.) Do
377     not use identifiers which are reserved in ANSI C++. (E.g.
378     template, class, true, false, ...). This is in case we ever
379     decide to port Privoxy to C++.</para>
380
381     <para><emphasis>Example:</emphasis></para>
382 <programlisting>
383 int ms_iis5_hack = 0;</programlisting>
384
385     <para><emphasis>Instead of:</emphasis></para>
386
387     <para>
388 <programlisting>
389 int msiis5hack = 0; int msIis5Hack = 0;
390 </programlisting>
391 </para>
392
393     
394
395   </sect3>    
396
397     <sect3 id="s11"><title>Function Names</title>
398
399     <para><emphasis>Explanation:</emphasis></para>
400
401     <para>Use all lowercase, and seperate words via an underscore
402     ('_'). Do not start an identifier with an underscore. (ANSI C
403     reserves these for use by the compiler and system headers.) Do
404     not use identifiers which are reserved in ANSI C++. (E.g.
405     template, class, true, false, ...). This is in case we ever
406     decide to port Privoxy to C++.</para>
407
408     <para><emphasis>Example:</emphasis></para>
409 <programlisting>
410 int load_some_file( struct client_state *csp )</programlisting>
411
412     <para><emphasis>Instead of:</emphasis></para>
413
414     <para>
415 <programlisting>
416 int loadsomefile( struct client_state *csp )
417 int loadSomeFile( struct client_state *csp )
418 </programlisting>
419 </para>
420
421     
422   </sect3>
423     
424
425     <sect3 id="s12"><title>Header file prototypes</title>
426
427     <para><emphasis>Explanation:</emphasis></para>
428
429     <para>Use a descriptive parameter name in the function prototype
430     in header files. Use the same parameter name in the header file
431     that you use in the c file.</para>
432
433     <para><emphasis>Example:</emphasis></para>
434 <programlisting>
435 (.h) extern int load_aclfile( struct client_state *csp );
436 (.c) int load_aclfile( struct client_state *csp )</programlisting>
437
438     <para><emphasis>Instead of:</emphasis>
439 <programlisting>
440 (.h) extern int load_aclfile( struct client_state * ); or 
441 (.h) extern int load_aclfile(); 
442 (.c) int load_aclfile( struct client_state *csp )
443 </programlisting>
444 </para>
445
446     
447   </sect3>
448     
449
450     <sect3 id="s13"><title>Enumerations, and #defines</title>
451
452     <para><emphasis>Explanation:</emphasis></para>
453
454     <para>Use all capital letters, with underscores between words. Do
455     not start an identifier with an underscore. (ANSI C reserves
456     these for use by the compiler and system headers.)</para>
457
458     <para><emphasis>Example:</emphasis></para>
459 <programlisting>
460 (enumeration) : enum Boolean { FALSE, TRUE };
461 (#define) : #define DEFAULT_SIZE 100;</programlisting>
462
463     <para><emphasis>Note:</emphasis> We have a standard naming scheme for #defines
464     that toggle a feature in the preprocessor: FEATURE_>, where
465     > is a short (preferably 1 or 2 word) description.</para>
466
467     <para><emphasis>Example:</emphasis></para>
468 <programlisting>
469 #define FEATURE_FORCE 1
470
471 #ifdef FEATURE_FORCE
472 #define FORCE_PREFIX blah
473 #endif /* def FEATURE_FORCE */
474 </programlisting>
475   </sect3>
476     
477
478     <sect3 id="s14"><title>Constants</title>
479
480     <para><emphasis>Explanation:</emphasis></para>
481
482     <para>Spell common words out entirely (do not remove vowels).</para>
483
484     <para>Use only widely-known domain acronyms and abbreviations.
485     Capitalize all letters of an acronym.</para>
486
487     <para>Use underscore (_) to separate adjacent acronyms and
488     abbreviations. Never terminate a name with an underscore.</para>
489
490     <para><emphasis>Example:</emphasis></para>
491 <programlisting>
492 #define USE_IMAGE_LIST 1</programlisting>
493
494     <para><emphasis>Instead of:</emphasis></para>
495
496     <para>
497 <programlisting>
498 #define USE_IMG_LST 1 or 
499 #define _USE_IMAGE_LIST 1 or
500 #define USE_IMAGE_LIST_ 1 or 
501 #define use_image_list 1 or
502 #define UseImageList 1
503 </programlisting>
504 </para>
505
506     
507   </sect3>
508
509   </sect2>
510     
511
512     <sect2 id="s15"><title>Using Space</title>
513
514     
515
516     <sect3 id="s16"><title>Put braces on a line by themselves.</title>
517
518     <para><emphasis>Explanation:</emphasis></para>
519
520     <para>The brace needs to be on a line all by itself, not at the
521     end of the statement. Curly braces should line up with the
522     construct that they're associated with. This practice makes it
523     easier to identify the opening and closing braces for a
524     block.</para>
525
526     <para><emphasis>Example:</emphasis></para>
527 <programlisting>
528 if ( this == that )
529 {
530    ...
531 }</programlisting>
532
533     <para><emphasis>Instead of:</emphasis></para>
534
535     <para>if ( this == that ) { ... }</para>
536
537     <para>or</para>
538
539     <para>if ( this == that ) { ... }</para>
540
541     <para><emphasis>Note:</emphasis> In the special case that the if-statement is
542     inside a loop, and it is trivial, i.e. it tests for a
543     condidtion that is obvious from the purpose of the block,
544     one-liners as above may optically preserve the loop structure
545     and make it easier to read.</para>
546
547     <para><emphasis>Status:</emphasis> developer-discrection.</para>
548
549     <para><emphasis>Example exception:</emphasis></para>
550 <programlisting>
551 while ( more lines are read )
552 {
553    /* Please document what is/is not a comment line here */
554    if ( it's a comment ) continue;
555
556    do_something( line );
557 }
558 </programlisting>
559   </sect3>
560     
561
562     <sect3 id="s17"><title>ALL control statements should have a
563     block</title>
564
565     <para><emphasis>Explanation:</emphasis></para>
566
567     <para>Using braces to make a block will make your code more
568     readable and less prone to error. All control statements should
569     have a block defined.</para>
570
571     <para><emphasis>Example:</emphasis></para>
572 <programlisting>
573 if ( this == that )
574 {
575    DoSomething();
576    DoSomethingElse();
577 }</programlisting>
578
579     <para><emphasis>Instead of:</emphasis></para>
580
581     <para>if ( this == that ) DoSomething(); DoSomethingElse();</para>
582
583     <para>or</para>
584
585     <para>if ( this == that ) DoSomething();</para>
586
587     <para><emphasis>Note:</emphasis> The first example in "Instead of" will execute
588     in a manner other than that which the developer desired (per
589     indentation). Using code braces would have prevented this
590     "feature". The "explanation" and "exception" from the point
591     above also applies.</para>
592
593     
594   </sect3>
595     
596
597     <sect3 id="s18"><title>Do not belabor/blow-up boolean
598     expressions</title>
599
600     <para><emphasis>Example:</emphasis></para>
601 <programlisting>
602 structure->flag = ( condition );</programlisting>
603
604     <para><emphasis>Instead of:</emphasis></para>
605
606     <para>if ( condition ) { structure->flag = 1; } else {
607     structure->flag = 0; }</para>
608
609     <para><emphasis>Note:</emphasis> The former is readable and consice. The later
610     is wordy and inefficient. Please assume that any developer new
611     to the project has at least a "good" knowledge of C/C++. (Hope
612     I do not offend by that last comment ... 8-)</para>
613
614     
615   </sect3>
616     
617
618     <sect3 id="s19"><title>Use white space freely because it is
619     free</title>
620
621     <para><emphasis>Explanation:</emphasis></para>
622
623     <para>Make it readable. The notable exception to using white space
624     freely is listed in the next guideline.</para>
625
626     <para><emphasis>Example:</emphasis></para>
627 <programlisting>
628 int firstValue   = 0;
629 int someValue    = 0;
630 int anotherValue = 0;
631 int thisVariable = 0;
632
633 if ( thisVariable == thatVariable )
634
635 firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
636 </programlisting>
637   </sect3>
638     
639
640     <sect3 id="s20"><title>Don't use white space around structure
641     operators</title>
642
643     <para><emphasis>Explanation:</emphasis></para>
644
645     <para>- structure pointer operator ( "->" ) - member operator (
646     "." ) - functions and parentheses</para>
647
648     <para>It is a general coding practice to put pointers, references,
649     and function parentheses next to names. With spaces, the
650     connection between the object and variable/function name is not
651     as clear.</para>
652
653     <para><emphasis>Example:</emphasis></para>
654 <programlisting>
655 aStruct->aMember;
656 aStruct.aMember;
657 FunctionName();</programlisting>
658
659     <para><emphasis>Instead of:</emphasis> aStruct -> aMember; aStruct . aMember;
660     FunctionName ();</para>
661
662     
663   </sect3>
664     
665
666     <sect3 id="s21"><title>Make the last brace of a function stand
667     out</title>
668
669     <para><emphasis>Example:</emphasis></para>
670 <programlisting>
671 int function1( ... )
672 {
673    ...code...
674    return( retCode );
675
676 }   /* -END- function1 */
677
678
679 int function2( ... )
680 {
681 }   /* -END- function2 */
682 </programlisting>
683
684     <para><emphasis>Instead of:</emphasis></para>
685
686     <para>int function1( ... ) { ...code... return( retCode ); } int
687     function2( ... ) { }</para>
688
689     <para><emphasis>Note:</emphasis> Use 1 blank line before the closing brace and 2
690     lines afterwards. This makes the end of function standout to
691     the most casual viewer. Although function comments help
692     seperate functions, this is still a good coding practice. In
693     fact, I follow these rules when using blocks in "for", "while",
694     "do" loops, and long if {} statements too. After all whitespace
695     is free!</para>
696
697     <para><emphasis>Status:</emphasis> developer-discrection on the number of blank
698     lines. Enforced is the end of function comments.</para>
699
700     
701   </sect3>
702     
703
704     <sect3 id="s22"><title>Use 3 character indentions</title>
705
706     <para><emphasis>Explanation:</emphasis></para>
707
708     <para>If some use 8 character TABs and some use 3 character TABs,
709     the code can look *very* ragged. So use 3 character indentions
710     only. If you like to use TABs, pass your code through a filter
711     such as "expand -t3" before checking in your code.</para>
712
713     <para><emphasis>Example:</emphasis></para>
714 <programlisting>
715 static const char * const url_code_map[256] =
716 {
717    NULL, ...
718 };
719
720
721 int function1( ... )
722 {
723    if ( 1 )
724    {
725       return( ALWAYS_TRUE );
726    }
727    else
728    {
729       return( HOW_DID_YOU_GET_HERE );
730    }
731
732    return( NEVER_GETS_HERE );
733
734 }
735 </programlisting>
736   </sect3>
737
738   </sect2>
739     
740
741     <sect2 id="s23"><title>Initializing</title>
742
743     
744
745     <sect3 id="s24"><title>Initialize all variables</title>
746
747     <para><emphasis>Explanation:</emphasis></para>
748
749     <para>Do not assume that the variables declared will not be used
750     until after they have been assigned a value somewhere else in
751     the code. Remove the chance of accidentally using an unassigned
752     variable.</para>
753
754     <para><emphasis>Example:</emphasis></para>
755 <programlisting>
756 short anShort = 0;
757 float aFloat  = 0;
758 struct *ptr = NULL;</programlisting>
759
760     <para><emphasis>Note:</emphasis> It is much easier to debug a SIGSEGV if the
761     message says you are trying to access memory address 00000000
762     and not 129FA012; or arrayPtr[20] causes a SIGSEV vs.
763     arrayPtr[0].</para>
764
765     <para><emphasis>Status:</emphasis> developer-discrection if and only if the
766     variable is assigned a value "shortly after" declaration.</para>
767
768   </sect3>
769   </sect2>
770     
771
772     <sect2 id="s25"><title>Functions</title>
773
774     
775
776     <sect3 id="s26"><title>Name functions that return a boolean as a
777     question.</title>
778
779     <para><emphasis>Explanation:</emphasis></para>
780
781     <para>Value should be phrased as a question that would logically
782     be answered as a true or false statement</para>
783
784     <para><emphasis>Example:</emphasis></para>
785 <programlisting>
786 ShouldWeBlockThis();
787 ContainsAnImage();
788 IsWebPageBlank();
789 </programlisting>
790   </sect3>
791     
792
793     <sect3 id="s27"><title>Always specify a return type for a
794     function.</title>
795
796     <para><emphasis>Explanation:</emphasis></para>
797
798     <para>The default return for a function is an int. To avoid
799     ambiguity, create a return for a function when the return has a
800     purpose, and create a void return type if the function does not
801     need to return anything.</para>
802
803     
804   </sect3>
805     
806
807     <sect3 id="s28"><title>Minimize function calls when iterating by
808     using variables</title>
809
810     <para><emphasis>Explanation:</emphasis></para>
811
812     <para>It is easy to write the following code, and a clear argument
813     can be made that the code is easy to understand:</para>
814
815     <para><emphasis>Example:</emphasis></para>
816 <programlisting>
817 for ( size_t cnt = 0; cnt &lt; blockListLength(); cnt ++ )
818 {
819    ....
820 }</programlisting>
821
822     <para><emphasis>Note:</emphasis> Unfortunately, this makes a function call for
823     each and every iteration. This increases the overhead in the
824     program, because the compiler has to look up the function each
825     time, call it, and return a value. Depending on what occurs in
826     the blockListLength() call, it might even be creating and
827     destroying structures with each iteration, even though in each
828     case it is comparing "cnt" to the same value, over and over.
829     Remember too - even a call to blockListLength() is a function
830     call, with the same overhead.</para>
831
832     <para>Instead of using a function call during the iterations,
833     assign the value to a variable, and evaluate using the
834     variable.</para>
835
836     <para><emphasis>Example:</emphasis></para>
837 <programlisting>
838 size_t len = blockListLength();
839
840 for ( size_t cnt = 0; cnt &lt; len; cnt ++ )
841 {
842    ....
843 }</programlisting>
844
845     <para><emphasis>Exceptions:</emphasis> if the value of blockListLength() *may*
846     change or could *potentially* change, then you must code the
847     function call in the for/while loop.</para>
848
849     
850   </sect3>
851     
852
853     <sect3 id="s29"><title>Pass and Return by Const Reference</title>
854
855     <para><emphasis>Explanation:</emphasis></para>
856
857     <para>This allows a developer to define a const pointer and call
858     your function. If your function does not have the const
859     keyword, we may not be able to use your function. Consider
860     strcmp, if it were defined as: extern int strcmp( char *s1,
861     char *s2 );</para>
862
863     <para>I could then not use it to compare argv's in main: int main(
864     int argc, const char *argv[] ) { strcmp( argv[0], "privoxy"
865     ); }</para>
866
867     <para>Both these pointers are *const*! If the c runtime library
868     maintainers do it, we should too.</para>
869
870     
871   </sect3>
872     
873
874     <sect3 id="s30"><title>Pass and Return by Value</title>
875
876     <para><emphasis>Explanation:</emphasis></para>
877
878     <para>Most structures cannot fit onto a normal stack entry (i.e.
879     they are not 4 bytes or less). Aka, a function declaration
880     like: int load_aclfile( struct client_state csp )</para>
881
882     <para>would not work. So, to be consistent, we should declare all
883     prototypes with "pass by value": int load_aclfile( struct
884     client_state *csp )</para>
885
886     
887   </sect3>
888     
889
890     <sect3 id="s31"><title>Names of include files</title>
891
892     <para><emphasis>Explanation:</emphasis></para>
893
894     <para>Your include statements should contain the file name without
895     a path. The path should be listed in the Makefile, using -I as
896     processor directive to search the indicated paths. An exception
897     to this would be for some proprietary software that utilizes a
898     partial path to distinguish their header files from system or
899     other header files.</para>
900
901     <para><emphasis>Example:</emphasis></para>
902 <programlisting>
903 #include &lt;iostream.h&gt;     /* This is not a local include */
904 #include "config.h"       /* This IS a local include */
905 </programlisting>
906
907     <para><emphasis>Exception:</emphasis></para>
908
909     <para>
910 <programlisting>
911 /* This is not a local include, but requires a path element. */ 
912 #include &lt;sys/fileName.h&gt;
913 </programlisting>
914 </para>
915
916     <para><emphasis>Note:</emphasis> Please! do not add "-I." to the Makefile
917     without a _very_ good reason. This duplicates the #include
918     "file.h" behaviour.</para>
919
920     
921   </sect3>
922     
923
924     <sect3 id="s32"><title>Provide multiple inclusion
925     protection</title>
926
927     <para><emphasis>Explanation:</emphasis></para>
928
929     <para>Prevents compiler and linker errors resulting from
930     redefinition of items.</para>
931
932     <para>Wrap each header file with the following syntax to prevent
933     multiple inclusions of the file. Of course, replace PROJECT_H
934     with your file name, with "." Changed to "_", and make it
935     uppercase.</para>
936
937     <para><emphasis>Example:</emphasis></para>
938 <programlisting>
939 #ifndef PROJECT_H_INCLUDED
940 #define PROJECT_H_INCLUDED
941  ...
942 #endif /* ndef PROJECT_H_INCLUDED */
943 </programlisting>
944   </sect3>
945     
946
947     <sect3 id="s33"><title>Use `extern "C"` when appropriate</title>
948
949     <para><emphasis>Explanation:</emphasis></para>
950
951     <para>If our headers are included from C++, they must declare our
952     functions as `extern "C"`. This has no cost in C, but increases
953     the potential re-usability of our code.</para>
954
955     <para><emphasis>Example:</emphasis></para>
956 <programlisting>
957 #ifdef __cplusplus
958 extern "C"
959 {
960 #endif /* def __cplusplus */
961
962 ... function definitions here ...
963
964 #ifdef __cplusplus
965 }
966 #endif /* def __cplusplus */
967 </programlisting>
968   </sect3>
969     
970
971     <sect3 id="s34"><title>Where Possible, Use Forward Struct
972     Declaration Instead of Includes</title>
973
974     <para><emphasis>Explanation:</emphasis></para>
975
976     <para>Useful in headers that include pointers to other struct's.
977     Modifications to excess header files may cause needless
978     compiles.</para>
979
980     <para><emphasis>Example:</emphasis></para>
981 <programlisting>
982 /*********************************************************************
983  * We're avoiding an include statement here!
984  *********************************************************************/
985 struct file_list;
986 extern file_list *xyz;</programlisting>
987
988     <para><emphasis>Note:</emphasis> If you declare "file_list xyz;" (without the
989     pointer), then including the proper header file is necessary.
990     If you only want to prototype a pointer, however, the header
991     file is unneccessary.</para>
992
993     <para><emphasis>Status:</emphasis> Use with discrection.</para>
994
995     
996   </sect3>
997   </sect2>
998
999     <sect2 id="s35"><title>General Coding Practices</title>
1000
1001     
1002
1003     <sect3 id="s36"><title>Turn on warnings</title>
1004
1005     <para><emphasis>Explanation</emphasis></para>
1006
1007     <para>Compiler warnings are meant to help you find bugs. You
1008     should turn on as many as possible. With GCC, the switch is
1009     "-Wall". Try and fix as many warnings as possible.</para>
1010
1011     
1012   </sect3>
1013     
1014
1015     <sect3 id="s37"><title>Provide a default case for all switch
1016     statements</title>
1017
1018     <para><emphasis>Explanation:</emphasis></para>
1019
1020     <para>What you think is guaranteed is never really guaranteed. The
1021     value that you don't think you need to check is the one that
1022     someday will be passed. So, to protect yourself from the
1023     unknown, always have a default step in a switch statement.</para>
1024
1025     <para><emphasis>Example:</emphasis></para>
1026 <programlisting>
1027 switch( hash_string( cmd ) )
1028 {
1029    case hash_actions_file :
1030       ... code ...
1031       break;
1032
1033    case hash_confdir :
1034       ... code ...
1035       break;
1036
1037    default :
1038       log_error( ... );
1039       ... anomly code goes here ...
1040       continue; / break; / exit( 1 ); / etc ...
1041
1042 } /* end switch( hash_string( cmd ) ) */</programlisting>
1043
1044     <para><emphasis>Note:</emphasis> If you already have a default condition, you
1045     are obviously exempt from this point. Of note, most of the
1046     WIN32 code calls `DefWindowProc' after the switch statement.
1047     This API call *should* be included in a default statement.</para>
1048
1049     <para><emphasis>Another Note:</emphasis> This is not so much a readability issue
1050     as a robust programming issue. The "anomly code goes here" may
1051     be no more than a print to the STDERR stream (as in
1052     load_config). Or it may really be an ABEND condition.</para>
1053
1054     <para><emphasis>Status:</emphasis> Programmer discretion is advised.</para>
1055
1056     
1057   </sect3>
1058     
1059
1060     <sect3 id="s38"><title>Try to avoid falling through cases in a
1061     switch statement.</title>
1062
1063     <para><emphasis>Explanation:</emphasis></para>
1064
1065     <para>In general, you will want to have a 'break' statement within
1066     each 'case' of a switch statement. This allows for the code to
1067     be more readable and understandable, and furthermore can
1068     prevent unwanted surprises if someone else later gets creative
1069     and moves the code around.</para>
1070
1071     <para>The language allows you to plan the fall through from one
1072     case statement to another simply by omitting the break
1073     statement within the case statement. This feature does have
1074     benefits, but should only be used in rare cases. In general,
1075     use a break statement for each case statement.</para>
1076
1077     <para>If you choose to allow fall through, you should comment both
1078     the fact of the fall through and reason why you felt it was
1079     necessary.</para>
1080
1081     
1082   </sect3>
1083     
1084
1085     <sect3 id="s39"><title>Use 'long' or 'short' Instead of
1086     'int'</title>
1087
1088     <para><emphasis>Explanation:</emphasis></para>
1089
1090     <para>On 32-bit platforms, int usually has the range of long. On
1091     16-bit platforms, int has the range of short.</para>
1092
1093     <para><emphasis>Status:</emphasis> open-to-debate. In the case of most FSF
1094     projects (including X/GNU-Emacs), there are typedefs to int4,
1095     int8, int16, (or equivalence ... I forget the exact typedefs
1096     now). Should we add these to IJB now that we have a "configure"
1097     script?</para>
1098
1099     
1100   </sect3>
1101     
1102
1103     <sect3 id="s40"><title>Don't mix size_t and other types</title>
1104
1105     <para><emphasis>Explanation:</emphasis></para>
1106
1107     <para>The type of size_t varies across platforms. Do not make
1108     assumptions about whether it is signed or unsigned, or about
1109     how long it is. Do not compare a size_t against another
1110     variable of a different type (or even against a constant)
1111     without casting one of the values. Try to avoid using size_t if
1112     you can.</para>
1113
1114     
1115   </sect3>
1116     
1117
1118     <sect3 id="s41"><title>Declare each variable and struct on its
1119     own line.</title>
1120
1121     <para><emphasis>Explanation:</emphasis></para>
1122
1123     <para>It can be tempting to declare a series of variables all on
1124     one line. Don't.</para>
1125
1126     <para><emphasis>Example:</emphasis></para>
1127 <programlisting>
1128 long a = 0;
1129 long b = 0;
1130 long c = 0;</programlisting>
1131
1132     <para><emphasis>Instead of:</emphasis></para>
1133
1134     <para>long a, b, c;</para>
1135
1136     <para><emphasis>Explanation:</emphasis> - there is more room for comments on the
1137     individual variables - easier to add new variables without
1138     messing up the original ones - when searching on a variable to
1139     find its type, there is less clutter to "visually"
1140     eliminate</para>
1141
1142     <para><emphasis>Exceptions:</emphasis> when you want to declare a bunch of loop
1143     variables or other trivial variables; feel free to declare them
1144     on 1 line. You should, although, provide a good comment on
1145     their functions.</para>
1146
1147     <para><emphasis>Status:</emphasis> developer-discrection.</para>
1148
1149     
1150   </sect3>
1151     
1152
1153     <sect3 id="s42"><title>Use malloc/zalloc sparingly</title>
1154
1155     <para><emphasis>Explanation:</emphasis></para>
1156
1157     <para>Create a local stuct (on the stack) if the variable will
1158     live and die within the context of one function call.</para>
1159
1160     <para>Only "malloc" a struct (on the heap) if the variable's life
1161     will extend beyond the context of one function call.</para>
1162
1163     <para><emphasis>Example:</emphasis></para>
1164 <programlisting>
1165 If a function creates a struct and stores a pointer to it in a
1166 list, then it should definately be allocated via `malloc'.
1167 </programlisting>
1168   </sect3>
1169     
1170
1171     <sect3 id="s43"><title>The Programmer Who Uses 'malloc' is
1172     Responsible for Ensuring 'free'</title>
1173
1174     <para><emphasis>Explanation:</emphasis></para>
1175
1176     <para>If you have to "malloc" an instance, you are responsible for
1177     insuring that the instance is `free'd, even if the deallocation
1178     event falls within some other programmer's code. You are also
1179     responsible for ensuring that deletion is timely (i.e. not too
1180     soon, not too late). This is known as "low-coupling" and is a
1181     "good thing (tm)". You may need to offer a
1182     free/unload/destuctor type function to accomodate this.</para>
1183
1184     <para><emphasis>Example:</emphasis></para>
1185 <programlisting>
1186 int load_re_filterfile( struct client_state *csp ) { ... }
1187 static void unload_re_filterfile( void *f ) { ... }</programlisting>
1188
1189     <para><emphasis>Exceptions:</emphasis></para>
1190
1191     <para>The developer cannot be expected to provide `free'ing
1192     functions for C run-time library functions ... such as
1193     `strdup'.</para>
1194
1195     <para><emphasis>Status:</emphasis> developer-discrection. The "main" use of this
1196     standard is for allocating and freeing data structures (complex
1197     or nested).</para>
1198
1199     
1200   </sect3>
1201     
1202
1203     <sect3 id="s44"><title>Add loaders to the `file_list' structure
1204     and in order</title>
1205
1206     <para><emphasis>Explanation:</emphasis></para>
1207
1208     <para>I have ordered all of the "blocker" file code to be in alpha
1209     order. It is easier to add/read new blockers when you expect a
1210     certain order.</para>
1211
1212     <para><emphasis>Note:</emphasis> It may appear that the alpha order is broken in
1213     places by POPUP tests coming before PCRS tests. But since
1214     POPUPs can also be referred to as KILLPOPUPs, it is clear that
1215     it should come first.</para>
1216
1217     
1218   </sect3>
1219     
1220
1221     <sect3 id="s45"><title>"Uncertain" new code and/or changes to
1222     exitinst code, use FIXME</title>
1223
1224     <para><emphasis>Explanation:</emphasis></para>
1225
1226     <para>If you have enough confidence in new code or confidence in
1227     your changes, but are not *quite* sure of the reprocussions,
1228     add this:</para>
1229
1230     <para>/* FIXME: this code has a logic error on platform XYZ, *
1231     attempthing to fix */ #ifdef PLATFORM ...changed code here...
1232     #endif</para>
1233
1234     <para>or:</para>
1235
1236     <para>/* FIXME: I think the original author really meant this...
1237     */ ...changed code here...</para>
1238
1239     <para>or:</para>
1240
1241     <para>/* FIXME: new code that *may* break something else... */
1242     ...new code here...</para>
1243
1244     <para><emphasis>Note:</emphasis> If you make it clear that this may or may not
1245     be a "good thing (tm)", it will be easier to identify and
1246     include in the project (or conversly exclude from the
1247     project).</para>
1248
1249     
1250   </sect3>
1251
1252   </sect2>
1253
1254     <sect2 id="s46"><title>Addendum: Template for files and function
1255     comment blocks:</title>
1256
1257     <para><emphasis>Example for file comments:</emphasis></para>
1258 <programlisting>
1259 const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.14 2002/03/30 19:04:08 swa Exp $";
1260 /*********************************************************************
1261  *
1262  * File        :  $S<!-- Break CVS Substitution -->ource$
1263  *
1264  * Purpose     :  (Fill me in with a good description!)
1265  *
1266  * Copyright   :  Written by and Copyright (C) 2001 the SourceForge
1267  *                Privoxy team. http://www.privoxy.org/
1268  *
1269  *                Based on the Internet Junkbuster originally written
1270  *                by and Copyright (C) 1997 Anonymous Coders and
1271  *                Junkbusters Corporation.  http://www.junkbusters.com
1272  *
1273  *                This program is free software; you can redistribute it
1274  *                and/or modify it under the terms of the GNU General
1275  *                Public License as published by the Free Software
1276  *                Foundation; either version 2 of the License, or (at
1277  *                your option) any later version.
1278  *
1279  *                This program is distributed in the hope that it will
1280  *                be useful, but WITHOUT ANY WARRANTY; without even the
1281  *                implied warranty of MERCHANTABILITY or FITNESS FOR A
1282  *                PARTICULAR PURPOSE.  See the GNU General Public
1283  *                License for more details.
1284  *
1285  *                The GNU General Public License should be included with
1286  *                this file.  If not, you can view it at
1287  *                http://www.gnu.org/copyleft/gpl.html
1288  *                or write to the Free Software Foundation, Inc., 59
1289  *                Temple Place - Suite 330, Boston, MA  02111-1307, USA.
1290  *
1291  * Revisions   :
1292  *    $L<!-- Break CVS Substitution -->og$
1293  *
1294  *********************************************************************/
1295
1296
1297 #include "config.h"
1298
1299    ...necessary include files for us to do our work...
1300
1301 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1302 </programlisting>
1303
1304     <para><emphasis>Note:</emphasis> This declares the rcs variables that should be
1305     added to the "show-proxy-args" page. If this is a brand new
1306     creation by you, you are free to change the "Copyright" section
1307     to represent the rights you wish to maintain.</para>
1308
1309     <para><emphasis>Note:</emphasis> The formfeed character that is present right
1310     after the comment flower box is handy for (X|GNU)Emacs users to
1311     skip the verbige and get to the heart of the code (via
1312     `forward-page' and `backward-page'). Please include it if you
1313     can.</para>
1314
1315     <para><emphasis>Example for file header comments:</emphasis></para>
1316 <programlisting>
1317 #ifndef _FILENAME_H
1318 #define _FILENAME_H
1319 #define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.14 2002/03/30 19:04:08 swa Exp $"
1320 /*********************************************************************
1321  *
1322  * File        :  $S<!-- Break CVS Substitution -->ource$
1323  *
1324  * Purpose     :  (Fill me in with a good description!)
1325  *
1326  * Copyright   :  Written by and Copyright (C) 2001 the SourceForge
1327  *                Privoxy team. http://www.privoxy.org/
1328  *
1329  *                Based on the Internet Junkbuster originally written
1330  *                by and Copyright (C) 1997 Anonymous Coders and
1331  *                Junkbusters Corporation.  http://www.junkbusters.com
1332  *
1333  *                This program is free software; you can redistribute it
1334  *                and/or modify it under the terms of the GNU General
1335  *                Public License as published by the Free Software
1336  *                Foundation; either version 2 of the License, or (at
1337  *                your option) any later version.
1338  *
1339  *                This program is distributed in the hope that it will
1340  *                be useful, but WITHOUT ANY WARRANTY; without even the
1341  *                implied warranty of MERCHANTABILITY or FITNESS FOR A
1342  *                PARTICULAR PURPOSE.  See the GNU General Public
1343  *                License for more details.
1344  *
1345  *                The GNU General Public License should be included with
1346  *                this file.  If not, you can view it at
1347  *                http://www.gnu.org/copyleft/gpl.html
1348  *                or write to the Free Software Foundation, Inc., 59
1349  *                Temple Place - Suite 330, Boston, MA  02111-1307, USA.
1350  *
1351  * Revisions   :
1352  *    $L<!-- Break CVS Substitution -->og$
1353  *
1354  *********************************************************************/
1355
1356
1357 #include "project.h"
1358
1359 #ifdef __cplusplus
1360 extern "C" {
1361 #endif
1362
1363    ... function headers here ...
1364
1365
1366 /* Revision control strings from this header and associated .c file */
1367 extern const char FILENAME_rcs[];
1368 extern const char FILENAME_h_rcs[];
1369
1370
1371 #ifdef __cplusplus
1372 } /* extern "C" */
1373 #endif
1374
1375 #endif /* ndef _FILENAME_H */
1376
1377 /*
1378   Local Variables:
1379   tab-width: 3
1380   end:
1381 */
1382 </programlisting>
1383
1384     <para><emphasis>Example for function comments:</emphasis></para>
1385 <programlisting>
1386 /*********************************************************************
1387  *
1388  * Function    :  FUNCTION_NAME
1389  *
1390  * Description :  (Fill me in with a good description!)
1391  *
1392  * parameters  :
1393  *          1  :  param1 = pointer to an important thing
1394  *          2  :  x      = pointer to something else
1395  *
1396  * Returns     :  0 => Ok, everything else is an error.
1397  *
1398  *********************************************************************/
1399 int FUNCTION_NAME( void *param1, const char *x )
1400 {
1401    ...
1402    return( 0 );
1403
1404 }
1405 </programlisting>
1406
1407     <para><emphasis>Note:</emphasis> If we all follow this practice, we should be
1408     able to parse our code to create a "self-documenting" web
1409     page.</para>
1410
1411   </sect2>
1412
1413   </sect1>
1414
1415   <!--   ~~~~~       New section      ~~~~~     -->
1416   <sect1 id="cvs"><title>Version Control Guidelines</title>
1417     <para>To be filled. note on cvs comments. don't comment what you did, comment
1418 why you did it.
1419 </para>
1420   </sect1>
1421
1422   <!--   ~~~~~       New section      ~~~~~     -->
1423   <sect1 id="testing"><title>Testing Guidelines</title>
1424     <para>To be filled.
1425 </para>
1426
1427     <!--   ~~~~~       New section      ~~~~~     -->
1428     <sect2 id="testing-plan"><title>Testplan for releases</title>
1429       <para>
1430 Explain release numbers. major, minor. developer releases. etc.
1431
1432 <orderedlist numeration="arabic">
1433           <listitem><para>
1434 Remove any existing rpm with rpm -e
1435 </para></listitem>
1436           <listitem><para>
1437 Remove any file that was left over. This includes (but is not limited to)
1438       <itemizedlist>
1439                 <listitem><para>/var/log/privoxy</para></listitem>
1440                 <listitem><para>/etc/privoxy</para></listitem>
1441                 <listitem><para>/usr/sbin/privoxy</para></listitem>
1442                 <listitem><para>/etc/init.d/privoxy</para></listitem>
1443                 <listitem><para>/usr/doc/privoxy*</para></listitem>
1444               </itemizedlist>
1445 </para></listitem>
1446           <listitem><para>
1447 Install the rpm. Any error messages?
1448 </para></listitem>
1449           <listitem><para>start,stop,status <application>Privoxy</application> with the specific script
1450       (e.g. /etc/rc.d/init/privoxy stop). Reboot your machine. Does
1451       autostart work?</para></listitem>
1452           <listitem><para>Start browsing. Does <application>Privoxy</application> work? Logfile written?</para></listitem>
1453           <listitem><para>Remove the rpm. Any error messages? All files removed?</para></listitem>
1454         </orderedlist>
1455 </para>
1456     </sect2>
1457
1458     <!--   ~~~~~       New section      ~~~~~     -->
1459     <sect2 id="testing-report"><title>Test reports</title>
1460       <para>
1461 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>
1462 at sourceforge. Three simple steps:
1463         <itemizedlist>
1464           
1465           <listitem><para>Select category: the distribution you test on.</para></listitem>
1466           <listitem><para>Select group: the version of <application>Privoxy</application> that we are about to release.</para></listitem>
1467           <listitem><para>Fill the Summary and Detailed Description with something
1468               intelligent (keep it short and precise).</para>
1469           </listitem>
1470         </itemizedlist>
1471         Do not mail to the mailinglist (we cannot keep track on issues there).
1472       </para>
1473     </sect2>
1474     
1475   </sect1>
1476
1477   <!--   ~~~~~       New section      ~~~~~     -->
1478   <sect1 id="newrelease"><title>Releasing a new version</title>
1479     <para>
1480         To minimize trouble with distribution contents, webpage
1481         errors and the like, I (Stefan) strongly encourage you
1482         to follow this section if you prepare a new release of
1483         code or new pages on the webserver.
1484     </para>
1485     <para>
1486         The following programs are required to follow this process:
1487         <filename>ncftpput</filename> (ncftp), <filename>scp</filename> (ssh),
1488 <filename>gmake</filename> (GNU's version of make), ???.
1489     </para>
1490     <sect2 id="newrelease-web"><title>Update the webserver</title>
1491       <para>
1492         All files must be group-readable and group-writable (or no one else
1493         will be able to change them). To update the webserver, create any
1494         pages locally in the <filename>doc/webserver</filename> directory (or
1495         create new directories under <filename>doc/webserver</filename>), then do
1496         </para>
1497         <para>
1498         <programlisting>
1499         make webserver
1500         </programlisting>
1501         </para>
1502         <para>
1503         Note that <filename>make dok</filename> creates
1504         <filename>doc/webserver/user-manual</filename>,
1505         <filename>doc/webserver/developer-manual</filename>,
1506         <filename>doc/webserver/faq</filename> and
1507         <filename>doc/webserver/man-page</filename> automatically.
1508       </para>
1509       <para>
1510          Verify on the webserver that the permissions are set correctly.  Do
1511          NOT use any other means of transferring files to the webserver.
1512       </para>
1513     </sect2>
1514
1515     <sect2 id="newrelease-rpm"><title>SuSE or RedHat</title>
1516       <para>
1517         Ensure that you have the latest code version. Hence run
1518         </para>
1519         <para>
1520         <programlisting>
1521         cvs update .
1522         </programlisting>
1523         </para>
1524         <para>
1525         first. If necessary, change the version number of
1526         <application>Privoxy</application> in the
1527         <filename>configure.in</filename> file. Update the release number
1528         directly in the specific spec file (particularly, set the release
1529         number to <filename>1</filename> if you have increased the version
1530         number before). Run
1531         </para>
1532         <para>
1533         <programlisting>
1534         autoheader && autoconf && ./configure
1535         </programlisting>
1536         </para>
1537         <para>
1538         Then do
1539         </para>
1540         <para>
1541         <programlisting>
1542         make suse-dist or make redhat-dist
1543         </programlisting>
1544         </para>
1545         <para>
1546         To upload the package to Sourceforge, simply issue
1547         </para>
1548         <para>
1549         <programlisting>
1550         make suse-upload or make redhat-upload
1551         </programlisting>
1552         </para>
1553         <para>
1554         Goto the displayed URL and release the file publically on Sourceforge.
1555       </para>
1556     </sect2>
1557
1558     <sect2 id="newrelease-os2"><title>OS/2</title>
1559       <para>
1560         Ensure that you have the latest code version. Hence run
1561         </para>
1562         <para>
1563         <programlisting>
1564         cvs update .
1565         </programlisting>
1566         </para>
1567         <para>
1568         first. If necessary, change the version number of
1569         <application>Privoxy</application> in the
1570         <filename>configure.in</filename> file. Run
1571         </para>
1572         <para>
1573         <programlisting>
1574         autoheader && autoconf && ./configure
1575         </programlisting>
1576         </para>
1577         <para>
1578         Then do FIXME.
1579         </para>
1580     </sect2>
1581
1582     <sect2 id="newrelease-solaris"><title>Solaris</title>
1583       <para>
1584         Login to Sourceforge's compilefarm via ssh
1585         </para>
1586         <para>
1587         <programlisting>
1588         ssh cf.sourceforge.net
1589         </programlisting>
1590         </para>
1591         <para>
1592         Choose the right operating system (not the Debian one). If you have
1593         downloaded Privoxy before,
1594         </para>
1595         <para>
1596         <programlisting>
1597         cd current && cvs update .
1598         </programlisting>
1599         </para>
1600         <para>
1601         If not, please <ulink
1602         url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
1603         Privoxy via CVS first</ulink>. Verify the version number in
1604         <filename>configure.in</filename>. If necessary, change the version
1605         number. Run
1606         </para>
1607         <para>
1608         <programlisting>
1609         autoheader && autoconf && ./configure
1610         </programlisting>
1611         </para>
1612         <para>
1613         Then run
1614         </para>
1615         <para>
1616         <programlisting>
1617         gmake solaris-dist
1618         </programlisting>
1619         </para>
1620         <para>
1621         which creates a gzip'ed tar archive. Sadly, you cannot use <filename>make
1622         solaris-upload</filename> on the Sourceforge machine (no ncftpput). You now have
1623         to manually upload the archive to Sourceforge's ftp server and release
1624         the file publically
1625         </para>
1626     </sect2>
1627
1628     <sect2 id="newrelease-windows"><title>Windows</title>
1629       <para>
1630         Ensure that you have the latest code version. Hence run
1631         </para>
1632         <para>
1633         <programlisting>
1634         cvs update .
1635         </programlisting>
1636         </para>
1637         <para>
1638         first. If necessary, change the version number of
1639         <application>Privoxy</application> in the
1640         <filename>configure.in</filename> file. Run
1641         </para>
1642         <para>
1643         <programlisting>
1644         autoheader && autoconf && ./configure
1645         </programlisting>
1646         </para>
1647         <para>
1648         Then do FIXME.
1649         </para>
1650     </sect2>
1651
1652     <sect2 id="newrelease-debian"><title>Debian</title>
1653       <para>
1654         Ensure that you have the latest code version. Hence run
1655         </para>
1656         <para>
1657         <programlisting>
1658         cvs update .
1659         </programlisting>
1660         </para>
1661         <para>
1662         first. If necessary, change the version number of
1663         <application>Privoxy</application> in the
1664         <filename>configure.in</filename> file. Run
1665         </para>
1666         <para>
1667         <programlisting>
1668         autoheader && autoconf && ./configure
1669         </programlisting>
1670         </para>
1671         <para>
1672         Then do FIXME.
1673         </para>
1674     </sect2>
1675
1676     <sect2 id="newrelease-macosx"><title>Mac OSX</title>
1677       <para>
1678         Login to Sourceforge's compilefarm via ssh
1679         </para>
1680         <para>
1681         <programlisting>
1682         ssh cf.sourceforge.net
1683         </programlisting>
1684         </para>
1685         <para>
1686         Choose the right operating system. If you have downloaded Privoxy
1687         before,
1688         </para>
1689         <para>
1690         <programlisting>
1691         cd current && cvs update .
1692         </programlisting>
1693         </para>
1694         <para>
1695         If not, please <ulink
1696         url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
1697         Privoxy via CVS first</ulink>. Verify the version number in
1698         <filename>configure.in</filename>. If necessary, change the version
1699         number. Run
1700         </para>
1701         <para>
1702         <programlisting>
1703         autoheader && autoconf && ./configure
1704         </programlisting>
1705         </para>
1706         <para>
1707         Then run
1708         </para>
1709         <para>
1710         <programlisting>
1711         make macosx-dist
1712         </programlisting>
1713         </para>
1714         <para>
1715         which creates a gzip'ed tar archive. Sadly, you cannot use <filename>make
1716         macosx-upload</filename> on the Sourceforge machine (no ncftpput). You now have
1717         to manually upload the archive to Sourceforge's ftp server and release
1718         the file publically
1719         </para>
1720     </sect2>
1721
1722     <sect2 id="newrelease-freebsd"><title>FreeBSD</title>
1723       <para>
1724         Change the version number of <application>Privoxy</application> in the
1725         configure.in file. Run
1726         <programlisting>
1727         autoheader && autoconf && ./configure
1728         </programlisting>
1729         Then ...
1730       </para>
1731       <para>
1732         Login to Sourceforge's compilefarm via ssh
1733         </para>
1734         <para>
1735         <programlisting>
1736         ssh cf.sourceforge.net
1737         </programlisting>
1738         </para>
1739         <para>
1740         Choose the right operating system. If you have downloaded Privoxy
1741         before,
1742         </para>
1743         <para>
1744         <programlisting>
1745         cd current && cvs update .
1746         </programlisting>
1747         </para>
1748         <para>
1749         If not, please <ulink
1750         url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
1751         Privoxy via CVS first</ulink>. Verify the version number in
1752         <filename>configure.in</filename>. If necessary, change the version
1753         number. Run
1754         </para>
1755         <para>
1756         <programlisting>
1757         autoheader && autoconf && ./configure
1758         </programlisting>
1759         </para>
1760         <para>
1761         Then run
1762         </para>
1763         <para>
1764         <programlisting>
1765         gmake freebsd-dist
1766         </programlisting>
1767         </para>
1768         <para>
1769         which creates a gzip'ed tar archive. Sadly, you cannot use <filename>make
1770         freebsd-upload</filename> on the Sourceforge machine (no ncftpput). You now have
1771         to manually upload the archive to Sourceforge's ftp server and release
1772         the file publically
1773         </para>
1774     </sect2>
1775
1776     <sect2 id="newrelease-tarball"><title>Tarball</title>
1777       <para>
1778         Ensure that you have the latest code version. Hence run
1779         </para>
1780         <para>
1781         <programlisting>
1782         cvs update .
1783         </programlisting>
1784         </para>
1785         <para>
1786         first. If necessary, change the version number of
1787         <application>Privoxy</application> in the
1788         <filename>configure.in</filename> file. Run
1789         </para>
1790         <para>
1791         <programlisting>
1792         make clobber
1793         autoheader && autoconf && ./configure
1794         </programlisting>
1795         </para>
1796         <para>
1797         Then do
1798         </para>
1799         <para>
1800         <programlisting>
1801         make tarball-dist
1802         </programlisting>
1803         </para>
1804         <para>
1805         To upload the package to Sourceforge, simply issue
1806         </para>
1807         <para>
1808         <programlisting>
1809         make tarball-upload
1810         </programlisting>
1811         </para>
1812         <para>
1813         Goto the displayed URL and release the file publically on Sourceforge.
1814       </para>
1815     </sect2>
1816
1817     <sect2 id="newrelease-hpux"><title>HP-UX 11</title>
1818       <para>
1819         Ensure that you have the latest code version. Hence run
1820         </para>
1821         <para>
1822         <programlisting>
1823         cvs update .
1824         </programlisting>
1825         </para>
1826         <para>
1827         first. If necessary, change the version number of
1828         <application>Privoxy</application> in the
1829         <filename>configure.in</filename> file. Run
1830         </para>
1831         <para>
1832         <programlisting>
1833         autoheader && autoconf && ./configure
1834         </programlisting>
1835         </para>
1836         <para>
1837         Then do FIXME.
1838         </para>
1839     </sect2>
1840
1841     <sect2 id="newrelease-amiga"><title>Amiga OS</title>
1842       <para>
1843         Ensure that you have the latest code version. Hence run
1844         </para>
1845         <para>
1846         <programlisting>
1847         cvs update .
1848         </programlisting>
1849         </para>
1850         <para>
1851         first. If necessary, change the version number of
1852         <application>Privoxy</application> in the
1853         <filename>configure.in</filename> file. Run
1854         </para>
1855         <para>
1856         <programlisting>
1857         autoheader && autoconf && ./configure
1858         </programlisting>
1859         </para>
1860         <para>
1861         Then do FIXME.
1862         </para>
1863     </sect2>
1864
1865     <sect2 id="newrelease-aix"><title>AIX</title>
1866       <para>
1867         Login to Sourceforge's compilefarm via ssh
1868         </para>
1869         <para>
1870         <programlisting>
1871         ssh cf.sourceforge.net
1872         </programlisting>
1873         </para>
1874         <para>
1875         Choose the right operating system. If you have downloaded Privoxy
1876         before,
1877         </para>
1878         <para>
1879         <programlisting>
1880         cd current && cvs update .
1881         </programlisting>
1882         </para>
1883         <para>
1884         If not, please <ulink
1885         url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
1886         Privoxy via CVS first</ulink>. Verify the version number in
1887         <filename>configure.in</filename>. If necessary, change the version
1888         number. Run
1889         </para>
1890         <para>
1891         <programlisting>
1892         autoheader && autoconf && ./configure
1893         </programlisting>
1894         </para>
1895         <para>
1896         Then run
1897         </para>
1898         <para>
1899         <programlisting>
1900         make aix-dist
1901         </programlisting>
1902         </para>
1903         <para>
1904         which creates a gzip'ed tar archive. Sadly, you cannot use <filename>make
1905         aix-upload</filename> on the Sourceforge machine (no ncftpput). You now have
1906         to manually upload the archive to Sourceforge's ftp server and release
1907         the file publically
1908         </para>
1909     </sect2>
1910
1911   </sect1>
1912   
1913   <!--   ~~~~~       New section      ~~~~~     -->
1914   <sect1 id="contact"><title>Contact the developers</title>
1915     <para>Please see the user manual for information on how to contact the developers.
1916     </para>
1917   </sect1>
1918   
1919   <!--   ~~~~~       New section      ~~~~~     -->
1920   <sect1 id="copyright"><title>Copyright and History</title>
1921     <para>Please see the user manual for information on Copyright and History.
1922     </para>
1923   </sect1>
1924   
1925   <!--   ~~~~~       New section      ~~~~~     -->
1926   <sect1 id="seealso"><title>See also</title>
1927     <para>Please see the user manual for information on references.
1928     </para>
1929   </sect1>
1930
1931   <!--
1932
1933   This program is free software; you can redistribute it 
1934   and/or modify it under the terms of the GNU General
1935   Public License as published by the Free Software
1936   Foundation; either version 2 of the License, or (at
1937   your option) any later version.
1938
1939   This program is distributed in the hope that it will
1940   be useful, but WITHOUT ANY WARRANTY; without even the
1941   implied warranty of MERCHANTABILITY or FITNESS FOR A
1942   PARTICULAR PURPOSE.  See the GNU General Public
1943   License for more details.
1944
1945   The GNU General Public License should be included with
1946   this file.  If not, you can view it at
1947   http://www.gnu.org/copyleft/gpl.html
1948   or write to the Free Software Foundation, Inc., 59
1949   Temple Place - Suite 330, Boston, MA  02111-1307, USA.
1950
1951   $Log: developer-manual.sgml,v $
1952   Revision 1.14  2002/03/30 19:04:08  swa
1953   people release differently. no good.
1954   I want to make parts of the docs only.
1955
1956   Revision 1.13  2002/03/27 01:16:41  hal9
1957   ditto
1958
1959   Revision 1.12  2002/03/27 01:02:51  hal9
1960   Touch up on name change...
1961
1962   Revision 1.11  2002/03/26 22:29:55  swa
1963   we have a new homepage!
1964
1965   Revision 1.10  2002/03/24 12:33:01  swa
1966   more additions.
1967
1968   Revision 1.9  2002/03/24 11:01:05  swa
1969   name change
1970
1971   Revision 1.8  2002/03/23 15:13:11  swa
1972   renamed every reference to the old name with foobar.
1973   fixed "application foobar application" tag, fixed
1974   "the foobar" with "foobar". left junkbustser in cvs
1975   comments and remarks to history untouched.
1976
1977   Revision 1.7  2002/03/11 13:13:27  swa
1978   correct feedback channels
1979
1980   Revision 1.6  2002/02/24 14:25:06  jongfoster
1981   Formatting changes.  Now changing the doctype to DocBook XML 4.1
1982   will work - no other changes are needed.
1983
1984   Revision 1.5  2001/10/31 18:16:51  swa
1985   documentation added: howto generate docs in text and html
1986   format, howto move stuff to the webserver.
1987
1988   Revision 1.4  2001/09/23 10:13:48  swa
1989   upload process established. run make webserver and
1990   the documentation is moved to the webserver. documents
1991   are now linked correctly.
1992
1993   Revision 1.3  2001/09/13 15:27:40  swa
1994   cosmetics
1995
1996   Revision 1.2  2001/09/13 15:20:17  swa
1997   merged standards into developer manual
1998
1999   Revision 1.1  2001/09/12 15:36:41  swa
2000   source files for junkbuster documentation
2001
2002   Revision 1.3  2001/09/10 17:43:59  swa
2003   first proposal of a structure.
2004
2005   Revision 1.2  2001/06/13 14:28:31  swa
2006   docs should have an author.
2007
2008   Revision 1.1  2001/06/13 14:20:37  swa
2009   first import of project's documentation for the webserver.
2010
2011   -->
2012
2013 </article>