doc/source/developer-manual.sgml

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