doc/source/developer-manual.sgml

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