doc/source/developer-manual.sgml

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