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.13">
  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.28 2002/04/08 22:59:26 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.28 2002/04/08 22:59:26 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.28 2002/04/08 22:59:26 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.28 2002/04/08 22:59:26 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.28  2002/04/08 22:59:26  hal9
2418   Version update. Spell chkconfig correctly :)
2419
2420   Revision 1.27  2002/04/08 15:31:18  hal9
2421   Touch ups to documentation section.
2422
2423   Revision 1.26  2002/04/07 23:50:08  hal9
2424   Documentation changes to reflect HTML docs now in CVS, and new generated files
2425   list.
2426
2427   Revision 1.25  2002/04/06 05:07:28  hal9
2428   -Add privoxy-man-page.sgml, for man page.
2429   -Add authors.sgml for AUTHORS (and p-authors.sgml)
2430   -Reworked various aspects of various docs.
2431   -Added additional comments to sub-docs.
2432
2433   Revision 1.24  2002/04/04 21:33:37  hal9
2434   More on documenting the documents.
2435
2436   Revision 1.23  2002/04/04 18:46:47  swa
2437   consistent look. reuse of copyright, history et. al.
2438
2439   Revision 1.22  2002/04/04 17:27:56  swa
2440   more single file to be included at multiple points. make maintaining easier
2441
2442   Revision 1.21  2002/04/04 06:48:37  hal9
2443   Structural changes to allow for conditional inclusion/exclusion of content
2444   based on entity toggles, e.g. 'entity % p-not-stable  "INCLUDE"'. And
2445   definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
2446   eventually be set by Makefile.
2447   More boilerplate text for use across multiple docs.
2448
2449   Revision 1.20  2002/04/04 03:28:27  david__schmidt
2450   Add Mac OSX section
2451
2452   Revision 1.19  2002/04/03 15:09:42  david__schmidt
2453   Add OS/2 build section
2454
2455   Revision 1.18  2002/04/03 03:51:48  hal9
2456   Touch ups.
2457
2458   Revision 1.17  2002/04/03 01:21:17  hal9
2459   Implementing Andreas's suggestions for Release sections.
2460
2461   Revision 1.16  2002/03/31 23:04:40  hal9
2462   Fleshed out the doc section, and added something for an intro so it was not
2463   blank.
2464
2465   Revision 1.15  2002/03/30 22:29:47  swa
2466   wrong make flavour
2467
2468   Revision 1.14  2002/03/30 19:04:08  swa
2469   people release differently. no good.
2470   I want to make parts of the docs only.
2471
2472   Revision 1.13  2002/03/27 01:16:41  hal9
2473   ditto
2474
2475   Revision 1.12  2002/03/27 01:02:51  hal9
2476   Touch up on name change...
2477
2478   Revision 1.11  2002/03/26 22:29:55  swa
2479   we have a new homepage!
2480
2481   Revision 1.10  2002/03/24 12:33:01  swa
2482   more additions.
2483
2484   Revision 1.9  2002/03/24 11:01:05  swa
2485   name change
2486
2487   Revision 1.8  2002/03/23 15:13:11  swa
2488   renamed every reference to the old name with foobar.
2489   fixed "application foobar application" tag, fixed
2490   "the foobar" with "foobar". left junkbustser in cvs
2491   comments and remarks to history untouched.
2492
2493   Revision 1.7  2002/03/11 13:13:27  swa
2494   correct feedback channels
2495
2496   Revision 1.6  2002/02/24 14:25:06  jongfoster
2497   Formatting changes.  Now changing the doctype to DocBook XML 4.1
2498   will work - no other changes are needed.
2499
2500   Revision 1.5  2001/10/31 18:16:51  swa
2501   documentation added: howto generate docs in text and html
2502   format, howto move stuff to the webserver.
2503
2504   Revision 1.4  2001/09/23 10:13:48  swa
2505   upload process established. run make webserver and
2506   the documentation is moved to the webserver. documents
2507   are now linked correctly.
2508
2509   Revision 1.3  2001/09/13 15:27:40  swa
2510   cosmetics
2511
2512   Revision 1.2  2001/09/13 15:20:17  swa
2513   merged standards into developer manual
2514
2515   Revision 1.1  2001/09/12 15:36:41  swa
2516   source files for junkbuster documentation
2517
2518   Revision 1.3  2001/09/10 17:43:59  swa
2519   first proposal of a structure.
2520
2521   Revision 1.2  2001/06/13 14:28:31  swa
2522   docs should have an author.
2523
2524   Revision 1.1  2001/06/13 14:20:37  swa
2525   first import of project's documentation for the webserver.
2526
2527   -->
2528
2529 </article>