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.30 2002/04/11 09:24:53 oes 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.30 2002/04/11 09:24:53 oes 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.30 2002/04/11 09:24:53 oes 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.30 2002/04/11 09:24:53 oes 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     <para>
1863         Replace X, Y and Z with the actual version number (X = major, Y = minor, Z = point):
1864     </para>
1865
1866     <sect2 id="beforerelease">
1867     <title>Before the Release</title>
1868      <para>
1869        The following <emphasis>must be done by one of the
1870        developers</emphasis> prior to each new release.
1871      </para>
1872      <para>
1873       <itemizedlist>
1874        <listitem>
1875         <para>
1876          Make sure that everybody who has worked on the code in the last
1877          couple of days has had a chance to yell <quote>no!</quote> in case
1878          they have pending changes/fixes in their pipelines.
1879         </para>
1880       </listitem>
1881       <listitem>
1882        <para>
1883          Increment the version number in <filename>configure.in</filename> in
1884          CVS. Also, inrease or reset the RPM release number in
1885          <filename>configure.in</filename> as appropriate. Do <emphasis>NOT</emphasis>
1886          touch version information after export from CVS.
1887          <emphasis>All packages</emphasis> will use the version and release data
1888          from <filename>configure.in</filename>.
1889          Local files should not be changed, except prior to a CVS commit!!!
1890          This way we are all on the same page!
1891        </para>
1892       </listitem>
1893       <listitem>
1894        <para>
1895         If the default actionsfile has changed since last release,
1896         bump up its version info in this line:
1897        </para>
1898        <para>
1899         <programlisting>
1900   {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
1901         </programlisting>
1902        </para>
1903        <para>
1904         Then change the version info in doc/webserver/actions/index.php,
1905         line: '$required_actions_file_version = "A.B";'
1906        </para>
1907       </listitem>
1908       <listitem>
1909        <para>
1910         <emphasis>Commit all files that were changed in the above steps!</emphasis>
1911        </para>
1912       </listitem>
1913       <listitem>
1914        <para>
1915         Tag all files in CVS with the version number with
1916         <quote><command>cvs tag v_X_Y_Z</command></quote>.
1917         Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
1918        </para>
1919       </listitem>
1920       <listitem>
1921        <para>
1922         The first package uploaded should be the official
1923         <quote>tarball</quote> release. This is built with the
1924         <quote><command>make tarball-dist</command></quote> Makefile
1925         target, and then can be uploaded with
1926         <quote><command>make tarball-upload</command></quote> (see below).
1927        </para>
1928       </listitem>
1929       </itemizedlist>
1930      </para>
1931     </sect2>
1932
1933     <sect2 id="newrelease-web"><title>Update the webserver</title>
1934       <para>
1935         All files must be group-readable and group-writable (or no one else
1936         will be able to change them). To update the webserver, create any
1937         pages locally in the <filename>doc/webserver</filename> directory (or
1938         create new directories under <filename>doc/webserver</filename>), then do
1939         </para>
1940         <para>
1941         <programlisting>
1942   make webserver
1943         </programlisting>
1944         </para>
1945         <para>
1946         Note that <quote><command>make dok</command></quote>
1947      (or <quote><command>make redhat-dok</command></quote>) creates
1948         <filename>doc/webserver/user-manual</filename>,
1949         <filename>doc/webserver/developer-manual</filename>,
1950         <filename>doc/webserver/faq</filename> and
1951         <filename>doc/webserver/man-page</filename> automatically.
1952       </para>
1953       <para>
1954       Please do NOT use any other means of transferring files to the
1955       webserver. <quote><command>make webserver</command></quote> not only
1956       uploads, but will make sure that the appropriate permissions are
1957       preserved for shared group access.
1958       </para>
1959     </sect2>
1960
1961     <sect2 id="newrelease-rpm"><title>SuSE or Red Hat</title>
1962       <para>
1963         Ensure that you have the latest code version. Hence run:
1964         </para>
1965         <para>
1966         <programlisting>
1967   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
1968   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
1969   cd current
1970         </programlisting>
1971         </para>
1972         <para>
1973          first.
1974         </para>
1975         <para>
1976         <programlisting>
1977   autoheader && autoconf && ./configure
1978         </programlisting>
1979         </para>
1980         <para>
1981         Then do
1982         </para>
1983         <para>
1984         <programlisting>
1985   make suse-dist or make redhat-dist
1986         </programlisting>
1987         </para>
1988         <para>
1989         To upload the package to Sourceforge, simply issue
1990         </para>
1991         <para>
1992         <programlisting>
1993   make suse-upload or make redhat-upload
1994         </programlisting>
1995         </para>
1996         <para>
1997         Go to the displayed URL and release the file publicly on Sourceforge.
1998       </para>
1999     </sect2>
2000
2001     <sect2 id="newrelease-os2"><title>OS/2</title>
2002       <para>
2003         Ensure that you have the latest code version. Hence run:
2004         </para>
2005         <para>
2006         <programlisting>
2007   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2008   cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
2009   cd ..
2010   cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
2011         </programlisting>
2012         </para>
2013         <para>
2014         You will need a mix of development tools.
2015         The main compilation takes place with IBM Visual Age C++.
2016         Some ancillary work takes place with GNU tools, available from
2017         various sources like hobbes.nmsu.edu.
2018         Specificially, you will need <filename>autoheader</filename>,
2019         <filename>autoconf</filename> and <filename>sh</filename> tools.
2020         The packaging takes place with WarpIN, available from various sources, including
2021         its home page: <ulink url="http://www.xworkplace.org/">xworkplace</ulink>.
2022         </para>
2023         <para>
2024         Change directory to the <filename>os2setup</filename> directory.
2025         Edit the os2build.cmd file to set the final executable filename.
2026         For example,
2027         <programlisting>
2028   installExeName='privoxyos2_setup_X.Y.Z.exe'
2029         </programlisting>
2030         Next, edit the <filename>IJB.wis</filename> file so the release number matches
2031         in the <filename>PACKAGEID</filename> section:
2032         <programlisting>
2033   PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
2034         </programlisting>
2035         You're now ready to build.  Run:
2036         <programlisting>
2037   os2build
2038         </programlisting>
2039      And in the <filename>./files</filename> directory you will have the
2040      WarpIN-installable executable.
2041      Upload this anonymously to
2042      <filename>uploads.sourceforge.net/incoming</filename>, create a release
2043      for it, and you're done.
2044         </para>
2045     </sect2>
2046
2047     <sect2 id="newrelease-solaris"><title>Solaris</title>
2048       <para>
2049         Login to Sourceforge's compilefarm via ssh
2050         </para>
2051         <para>
2052         <programlisting>
2053   ssh cf.sourceforge.net
2054         </programlisting>
2055         </para>
2056         <para>
2057         Choose the right operating system (not the Debian one). If you have
2058         downloaded <application>Privoxy</application> before,
2059         </para>
2060         <para>
2061         <programlisting>
2062   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2063   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
2064   cd current
2065         </programlisting>
2066         </para>
2067         <para>
2068         If not, please <ulink
2069         url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
2070         Privoxy via CVS first</ulink>. Run:
2071         </para>
2072         <para>
2073         <programlisting>
2074   autoheader && autoconf && ./configure
2075         </programlisting>
2076         </para>
2077         <para>
2078         Then run
2079         </para>
2080         <para>
2081         <programlisting>
2082   gmake solaris-dist
2083         </programlisting>
2084         </para>
2085         <para>
2086         which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2087         solaris-upload</command> on the Sourceforge machine (no ncftpput). You now have
2088         to manually upload the archive to Sourceforge's ftp server and release
2089         the file publicly.
2090         </para>
2091     </sect2>
2092
2093     <sect2 id="newrelease-windows"><title>Windows</title>
2094       <para>
2095         Ensure that you have the latest code version. Hence run
2096         </para>
2097         <para>
2098         <programlisting>
2099   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2100   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
2101   cd current
2102         </programlisting>
2103         </para>
2104         <para>
2105          Run:
2106         </para>
2107         <para>
2108         <programlisting>
2109   autoheader && autoconf && ./configure
2110         </programlisting>
2111         </para>
2112         <para>
2113         Then do FIXME.
2114         </para>
2115     </sect2>
2116
2117     <sect2 id="newrelease-debian"><title>Debian</title>
2118       <para>
2119         Ensure that you have the latest code version. Hence run:
2120         </para>
2121         <para>
2122         <programlisting>
2123   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2124   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
2125   cd current
2126         </programlisting>
2127         </para>
2128         <para>
2129         first. Run:
2130         </para>
2131         <para>
2132         <programlisting>
2133   autoheader && autoconf && ./configure
2134         </programlisting>
2135         </para>
2136         <para>
2137         Then do FIXME.
2138         </para>
2139     </sect2>
2140
2141     <sect2 id="newrelease-macosx"><title>Mac OSX</title>
2142       <para>
2143         Ensure that you have the latest code version. Hence run:
2144         </para>
2145         <para>
2146         <programlisting>
2147   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2148   cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
2149   cd ..
2150   cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
2151         </programlisting>
2152         </para>
2153         <para>
2154         From the osxsetup directory, run:
2155         <programlisting>
2156   build
2157         </programlisting>
2158         </para>
2159         <para>
2160         This will run <filename>autoheader</filename>, <filename>autoconf</filename> and
2161         <filename>configure</filename> as well as <filename>make</filename>.
2162         Finally, it will copy over the necessary files to the ./osxsetup/files directory
2163         for further processing by <filename>PackageMaker</filename>.
2164         </para>
2165         <para>
2166         Bring up PackageMaker with the PrivoxyPackage.pmsp definition file, modify the package
2167         name to match the release, and hit the "Create package" button.
2168         If you specify ./Privoxy.pkg as the output package name, you can then create
2169         the distributable zip file with the command:
2170         <programlisting>
2171 zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
2172         </programlisting>
2173         You can then upload <filename>privoxyosx_setup_x.y.z.zip</filename> anonymously to
2174         <filename>uploads.sourceforge.net/incoming</filename>,
2175         create a release for it, and you're done.
2176         </para>
2177     </sect2>
2178
2179     <sect2 id="newrelease-freebsd"><title>FreeBSD</title>
2180       <para>
2181         Change the version number of <application>Privoxy</application> in the
2182         configure.in file. Run:
2183         <programlisting>
2184   autoheader && autoconf && ./configure
2185         </programlisting>
2186         Then ...
2187       </para>
2188       <para>
2189         Login to Sourceforge's compilefarm via ssh:
2190         </para>
2191         <para>
2192         <programlisting>
2193   ssh cf.sourceforge.net
2194         </programlisting>
2195         </para>
2196         <para>
2197         Choose the right operating system.
2198         </para>
2199         <para>
2200         <programlisting>
2201   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2202   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
2203   cd current
2204         </programlisting>
2205         </para>
2206         <para>
2207         Run:
2208         </para>
2209         <para>
2210         <programlisting>
2211   autoheader && autoconf && ./configure
2212         </programlisting>
2213         </para>
2214         <para>
2215         Then run:
2216         </para>
2217         <para>
2218         <programlisting>
2219   gmake freebsd-dist
2220         </programlisting>
2221         </para>
2222         <para>
2223         which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2224         freebsd-upload</command> on the Sourceforge machine (no ncftpput). You now have
2225         to manually upload the archive to Sourceforge's ftp server and release
2226         the file publicly.
2227         </para>
2228     </sect2>
2229
2230     <sect2 id="newrelease-tarball"><title>Tarball</title>
2231       <para>
2232         Ensure that you have the right code version. Hence run:
2233         </para>
2234         <para>
2235         <programlisting>
2236   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2237   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
2238   cd current
2239         </programlisting>
2240         </para>
2241         <para>
2242         first. Run:
2243         </para>
2244         <para>
2245         <programlisting>
2246   autoheader && autoconf && ./configure
2247         </programlisting>
2248         </para>
2249         <para>
2250         Then do:
2251         </para>
2252         <para>
2253         <programlisting>
2254   make tarball-dist
2255         </programlisting>
2256         </para>
2257         <para>
2258         To upload the package to Sourceforge, simply issue
2259         </para>
2260         <para>
2261         <programlisting>
2262   make tarball-upload
2263         </programlisting>
2264         </para>
2265         <para>
2266         Goto the displayed URL and release the file publicly on Sourceforge.
2267       </para>
2268     </sect2>
2269
2270     <sect2 id="newrelease-hpux"><title>HP-UX 11</title>
2271       <para>
2272         Ensure that you have the latest code version. Hence run:
2273         </para>
2274         <para>
2275         <programlisting>
2276   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2277   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
2278   cd current
2279         </programlisting>
2280         </para>
2281         <para>
2282         first. Run:
2283         </para>
2284         <para>
2285         <programlisting>
2286   autoheader && autoconf && ./configure
2287         </programlisting>
2288         </para>
2289         <para>
2290         Then do FIXME.
2291         </para>
2292     </sect2>
2293
2294     <sect2 id="newrelease-amiga"><title>Amiga OS</title>
2295       <para>
2296         Ensure that you have the latest code version. Hence run:
2297         </para>
2298         <para>
2299         <programlisting>
2300   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2301   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
2302   cd current
2303         </programlisting>
2304         </para>
2305         <para>
2306         first. Run:
2307         </para>
2308         <para>
2309         <programlisting>
2310   autoheader && autoconf && ./configure
2311         </programlisting>
2312         </para>
2313         <para>
2314         Then do FIXME.
2315         </para>
2316     </sect2>
2317
2318     <sect2 id="newrelease-aix"><title>AIX</title>
2319       <para>
2320         Login to Sourceforge's compilefarm via ssh:
2321         </para>
2322         <para>
2323         <programlisting>
2324   ssh cf.sourceforge.net
2325         </programlisting>
2326         </para>
2327         <para>
2328         Choose the right operating system. If you have downloaded Privoxy
2329         before:
2330         </para>
2331         <para>
2332         <programlisting>
2333   cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login
2334   cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r  v_X_Y_Z current
2335   cd current
2336         </programlisting>
2337         </para>
2338         <para>
2339         If not, please <ulink
2340         url="http://www.privoxy.org/user-manual/user-manual/installation.html#INSTALLATION-SOURCE">checkout
2341         Privoxy via CVS first</ulink>. Run:
2342         </para>
2343         <para>
2344         <programlisting>
2345   autoheader && autoconf && ./configure
2346         </programlisting>
2347         </para>
2348         <para>
2349         Then run:
2350         </para>
2351         <para>
2352         <programlisting>
2353   make aix-dist
2354         </programlisting>
2355         </para>
2356         <para>
2357         which creates a gzip'ed tar archive. Sadly, you cannot use <command>make
2358         aix-upload</command> on the Sourceforge machine (no ncftpput). You now have
2359         to manually upload the archive to Sourceforge's ftp server and release
2360         the file publicly.
2361         </para>
2362     </sect2>
2363
2364   </sect1>
2365
2366   <!--   ~~~~~       New section      ~~~~~     -->
2367   <sect1 id="contact"><title>Contacting the developers, Bug Reporting and Feature Requests</title>
2368 <!-- Include contacting.sgml  -->
2369  &contacting;
2370 <!-- end contacting -->
2371   </sect1>
2372
2373   <!--   ~~~~~       New section      ~~~~~     -->
2374   <sect1 id="copyright"><title>Copyright and History</title>
2375
2376 <sect2><title>Copyright</title>
2377 <!-- Include copyright.sgml -->
2378  &copyright;
2379 <!-- end -->
2380 </sect2>
2381
2382 <sect2><title>History</title>
2383 <!-- Include history.sgml -->
2384  &history;
2385 <!-- end -->
2386 </sect2>
2387
2388   </sect1>
2389
2390   <!--   ~~~~~       New section      ~~~~~     -->
2391   <sect1 id="seealso"><title>See also</title>
2392 <!-- Include seealso.sgml -->
2393  &seealso;
2394 <!-- end  -->
2395
2396   </sect1>
2397
2398   <!--
2399
2400   This program is free software; you can redistribute it
2401   and/or modify it under the terms of the GNU General
2402   Public License as published by the Free Software
2403   Foundation; either version 2 of the License, or (at
2404   your option) any later version.
2405
2406   This program is distributed in the hope that it will
2407   be useful, but WITHOUT ANY WARRANTY; without even the
2408   implied warranty of MERCHANTABILITY or FITNESS FOR A
2409   PARTICULAR PURPOSE.  See the GNU General Public
2410   License for more details.
2411
2412   The GNU General Public License should be included with
2413   this file.  If not, you can view it at
2414   http://www.gnu.org/copyleft/gpl.html
2415   or write to the Free Software Foundation, Inc., 59
2416   Temple Place - Suite 330, Boston, MA  02111-1307, USA.
2417
2418   $Log: developer-manual.sgml,v $
2419   Revision 1.30  2002/04/11 09:24:53  oes
2420   nits
2421
2422   Revision 1.29  2002/04/10 18:45:14  swa
2423   generated
2424
2425   Revision 1.28  2002/04/08 22:59:26  hal9
2426   Version update. Spell chkconfig correctly :)
2427
2428   Revision 1.27  2002/04/08 15:31:18  hal9
2429   Touch ups to documentation section.
2430
2431   Revision 1.26  2002/04/07 23:50:08  hal9
2432   Documentation changes to reflect HTML docs now in CVS, and new generated files
2433   list.
2434
2435   Revision 1.25  2002/04/06 05:07:28  hal9
2436   -Add privoxy-man-page.sgml, for man page.
2437   -Add authors.sgml for AUTHORS (and p-authors.sgml)
2438   -Reworked various aspects of various docs.
2439   -Added additional comments to sub-docs.
2440
2441   Revision 1.24  2002/04/04 21:33:37  hal9
2442   More on documenting the documents.
2443
2444   Revision 1.23  2002/04/04 18:46:47  swa
2445   consistent look. reuse of copyright, history et. al.
2446
2447   Revision 1.22  2002/04/04 17:27:56  swa
2448   more single file to be included at multiple points. make maintaining easier
2449
2450   Revision 1.21  2002/04/04 06:48:37  hal9
2451   Structural changes to allow for conditional inclusion/exclusion of content
2452   based on entity toggles, e.g. 'entity % p-not-stable  "INCLUDE"'. And
2453   definition of internal entities, e.g. 'entity p-version "2.9.13"' that will
2454   eventually be set by Makefile.
2455   More boilerplate text for use across multiple docs.
2456
2457   Revision 1.20  2002/04/04 03:28:27  david__schmidt
2458   Add Mac OSX section
2459
2460   Revision 1.19  2002/04/03 15:09:42  david__schmidt
2461   Add OS/2 build section
2462
2463   Revision 1.18  2002/04/03 03:51:48  hal9
2464   Touch ups.
2465
2466   Revision 1.17  2002/04/03 01:21:17  hal9
2467   Implementing Andreas's suggestions for Release sections.
2468
2469   Revision 1.16  2002/03/31 23:04:40  hal9
2470   Fleshed out the doc section, and added something for an intro so it was not
2471   blank.
2472
2473   Revision 1.15  2002/03/30 22:29:47  swa
2474   wrong make flavour
2475
2476   Revision 1.14  2002/03/30 19:04:08  swa
2477   people release differently. no good.
2478   I want to make parts of the docs only.
2479
2480   Revision 1.13  2002/03/27 01:16:41  hal9
2481   ditto
2482
2483   Revision 1.12  2002/03/27 01:02:51  hal9
2484   Touch up on name change...
2485
2486   Revision 1.11  2002/03/26 22:29:55  swa
2487   we have a new homepage!
2488
2489   Revision 1.10  2002/03/24 12:33:01  swa
2490   more additions.
2491
2492   Revision 1.9  2002/03/24 11:01:05  swa
2493   name change
2494
2495   Revision 1.8  2002/03/23 15:13:11  swa
2496   renamed every reference to the old name with foobar.
2497   fixed "application foobar application" tag, fixed
2498   "the foobar" with "foobar". left junkbustser in cvs
2499   comments and remarks to history untouched.
2500
2501   Revision 1.7  2002/03/11 13:13:27  swa
2502   correct feedback channels
2503
2504   Revision 1.6  2002/02/24 14:25:06  jongfoster
2505   Formatting changes.  Now changing the doctype to DocBook XML 4.1
2506   will work - no other changes are needed.
2507
2508   Revision 1.5  2001/10/31 18:16:51  swa
2509   documentation added: howto generate docs in text and html
2510   format, howto move stuff to the webserver.
2511
2512   Revision 1.4  2001/09/23 10:13:48  swa
2513   upload process established. run make webserver and
2514   the documentation is moved to the webserver. documents
2515   are now linked correctly.
2516
2517   Revision 1.3  2001/09/13 15:27:40  swa
2518   cosmetics
2519
2520   Revision 1.2  2001/09/13 15:20:17  swa
2521   merged standards into developer manual
2522
2523   Revision 1.1  2001/09/12 15:36:41  swa
2524   source files for junkbuster documentation
2525
2526   Revision 1.3  2001/09/10 17:43:59  swa
2527   first proposal of a structure.
2528
2529   Revision 1.2  2001/06/13 14:28:31  swa
2530   docs should have an author.
2531
2532   Revision 1.1  2001/06/13 14:20:37  swa
2533   first import of project's documentation for the webserver.
2534
2535   -->
2536
2537 </article>