-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
-Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+"http://www.w3.org/TR/html4/loose.dtd">
+
<html>
- <head>
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>
- Coding Guidelines
- </title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
- <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
- <link rel="PREVIOUS" title="Documentation Guidelines" href=
- "documentation.html">
- <link rel="NEXT" title="Testing Guidelines" href="testing.html">
- <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<style type="text/css">
- body {
+<head>
+ <meta name="generator" content=
+ "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
+
+ <title>Coding Guidelines</title>
+ <meta name="GENERATOR" content=
+ "Modular DocBook HTML Stylesheet Version 1.79">
+ <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
+ <link rel="PREVIOUS" title="Documentation Guidelines" href=
+ "documentation.html">
+ <link rel="NEXT" title="Testing Guidelines" href="testing.html">
+ <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+ <style type="text/css">
+body {
background-color: #EEEEEE;
color: #000000;
- }
- :link { color: #0000FF }
- :visited { color: #840084 }
- :active { color: #0000FF }
- hr.c1 {text-align: left}
-</style>
- </head>
- <body class="SECT1">
- <div class="NAVHEADER">
- <table summary="Header navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
- <tr>
- <th colspan="3" align="center">
- Privoxy Developer Manual
- </th>
- </tr>
- <tr>
- <td width="10%" align="left" valign="bottom">
- <a href="documentation.html" accesskey="P">Prev</a>
- </td>
- <td width="80%" align="center" valign="bottom">
- </td>
- <td width="10%" align="right" valign="bottom">
- <a href="testing.html" accesskey="N">Next</a>
- </td>
- </tr>
- </table>
- <hr width="100%" class="c1">
+ }
+ :link { color: #0000FF }
+ :visited { color: #840084 }
+ :active { color: #0000FF }
+ table.c3 {background-color: #E0E0E0}
+ span.c2 {font-style: italic}
+ hr.c1 {text-align: left}
+ </style>
+</head>
+
+<body class="SECT1">
+ <div class="NAVHEADER">
+ <table summary="Header navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <th colspan="3" align="center">Privoxy Developer Manual</th>
+ </tr>
+
+ <tr>
+ <td width="10%" align="left" valign="bottom"><a href=
+ "documentation.html" accesskey="P">Prev</a></td>
+
+ <td width="80%" align="center" valign="bottom"></td>
+
+ <td width="10%" align="right" valign="bottom"><a href="testing.html"
+ accesskey="N">Next</a></td>
+ </tr>
+ </table>
+ <hr class="c1" width="100%">
+ </div>
+
+ <div class="SECT1">
+ <h1 class="SECT1"><a name="CODING" id="CODING">4. Coding
+ Guidelines</a></h1>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="S1" id="S1">4.1. Introduction</a></h2>
+
+ <p>This set of standards is designed to make our lives easier. It is
+ developed with the simple goal of helping us keep the "new and improved
+ <span class="APPLICATION">Privoxy</span>" consistent and reliable. Thus
+ making maintenance easier and increasing chances of success of the
+ project.</p>
+
+ <p>And that of course comes back to us as individuals. If we can
+ increase our development and product efficiencies then we can solve
+ more of the request for changes/improvements and in general feel good
+ about ourselves. ;-></p>
</div>
- <div class="SECT1">
- <h1 class="SECT1">
- <a name="CODING">4. Coding Guidelines</a>
- </h1>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="S1">4.1. Introduction</a>
- </h2>
- <p>
- This set of standards is designed to make our lives easier. It is
- developed with the simple goal of helping us keep the "new and
- improved <span class="APPLICATION">Privoxy</span>" consistent and
- reliable. Thus making maintenance easier and increasing chances of
- success of the project.
- </p>
- <p>
- And that of course comes back to us as individuals. If we can
- increase our development and product efficiencies then we can solve
- more of the request for changes/improvements and in general feel
- good about ourselves. ;->
- </p>
- </div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="S2">4.2. Using Comments</a>
- </h2>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S3">4.2.1. Comment, Comment, Comment</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Comment as much as possible without commenting the obvious. For
- example do not comment "variable_a is equal to variable_b".
- Instead explain why variable_a should be equal to the variable_b.
- Just because a person can read code does not mean they will
- understand why or what is being done. A reader may spend a lot
- more time figuring out what is going on when a simple comment or
- explanation would have prevented the extra research. Please help
- your brother IJB'ers out!
- </p>
- <p>
- The comments will also help justify the intent of the code. If
- the comment describes something different than what the code is
- doing then maybe a programming error is occurring.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="S2" id="S2">4.2. Using Comments</a></h2>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S3" id="S3">4.2.1. Comment, Comment,
+ Comment</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Comment as much as possible without commenting the obvious. For
+ example do not comment "variable_a is equal to variable_b". Instead
+ explain why variable_a should be equal to the variable_b. Just
+ because a person can read code does not mean they will understand why
+ or what is being done. A reader may spend a lot more time figuring
+ out what is going on when a simple comment or explanation would have
+ prevented the extra research. Please help your brother IJB'ers
+ out!</p>
+
+ <p>The comments will also help justify the intent of the code. If the
+ comment describes something different than what the code is doing
+ then maybe a programming error is occurring.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
/* if page size greater than 1k ... */
if ( page_length() > 1024 )
{
"syntax comment". The second is a comment that does not fit what
is actually being done.
</pre>
- </td>
- </tr>
- </table>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S4">4.2.2. Use blocks for comments</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Comments can help or they can clutter. They help when they are
- differentiated from the code they describe. One line comments do
- not offer effective separation between the comment and the code.
- Block identifiers do, by surrounding the code with a clear,
- definable pattern.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S4" id="S4">4.2.2. Use blocks for
+ comments</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Comments can help or they can clutter. They help when they are
+ differentiated from the code they describe. One line comments do not
+ offer effective separation between the comment and the code. Block
+ identifiers do, by surrounding the code with a clear, definable
+ pattern.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
/*********************************************************************
* This will stand out clearly in your code!
*********************************************************************/
do_something_very_important();
}
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Exception:</i></span>
- </p>
- <p>
- If you are trying to add a small logic comment and do not wish to
- "disrupt" the flow of the code, feel free to use a 1 line comment
- which is NOT on the same line as the code.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S5">4.2.3. Keep Comments on their own line</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- It goes back to the question of readability. If the comment is on
- the same line as the code it will be harder to read than the
- comment that is on its own line.
- </p>
- <p>
- There are three exceptions to this rule, which should be violated
- freely and often: during the definition of variables, at the end
- of closing braces, when used to comment parameters.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Exception:</span></p>
+
+ <p>If you are trying to add a small logic comment and do not wish to
+ "disrupt" the flow of the code, feel free to use a 1 line comment
+ which is NOT on the same line as the code.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S5" id="S5">4.2.3. Keep Comments on their
+ own line</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>It goes back to the question of readability. If the comment is on
+ the same line as the code it will be harder to read than the comment
+ that is on its own line.</p>
+
+ <p>There are three exceptions to this rule, which should be violated
+ freely and often: during the definition of variables, at the end of
+ closing braces, when used to comment parameters.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
/*********************************************************************
* This will stand out clearly in your code,
* But the second example won't.
} /* -END- do_something_very_important */
</pre>
- </td>
- </tr>
- </table>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S6">4.2.4. Comment each logical step</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Logical steps should be commented to help others follow the
- intent of the written code and comments will make the code more
- readable.
- </p>
- <p>
- If you have 25 lines of code without a comment, you should
- probably go back into it to see where you forgot to put one.
- </p>
- <p>
- Most "for", "while", "do", etc... loops _probably_ need a
- comment. After all, these are usually major logic containers.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S7">4.2.5. Comment All Functions Thoroughly</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- A reader of the code should be able to look at the comments just
- prior to the beginning of a function and discern the reason for
- its existence and the consequences of using it. The reader should
- not have to read through the code to determine if a given
- function is safe for a desired use. The proper information
- thoroughly presented at the introduction of a function not only
- saves time for subsequent maintenance or debugging, it more
- importantly aids in code reuse by allowing a user to determine
- the safety and applicability of any function for the problem at
- hand. As a result of such benefits, all functions should contain
- the information presented in the addendum section of this
- document.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S8">4.2.6. Comment at the end of braces if the content
- is more than one screen length</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Each closing brace should be followed on the same line by a
- comment that describes the origination of the brace if the
- original brace is off of the screen, or otherwise far away from
- the closing brace. This will simplify the debugging, maintenance,
- and readability of the code.
- </p>
- <p>
- As a suggestion , use the following flags to make the comment and
- its brace more readable:
- </p>
- <p>
- use following a closing brace: } /* -END- if() or while () or
- etc... */
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S6" id="S6">4.2.4. Comment each logical
+ step</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Logical steps should be commented to help others follow the intent
+ of the written code and comments will make the code more
+ readable.</p>
+
+ <p>If you have 25 lines of code without a comment, you should
+ probably go back into it to see where you forgot to put one.</p>
+
+ <p>Most "for", "while", "do", etc... loops _probably_ need a comment.
+ After all, these are usually major logic containers.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S7" id="S7">4.2.5. Comment All Functions
+ Thoroughly</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>A reader of the code should be able to look at the comments just
+ prior to the beginning of a function and discern the reason for its
+ existence and the consequences of using it. The reader should not
+ have to read through the code to determine if a given function is
+ safe for a desired use. The proper information thoroughly presented
+ at the introduction of a function not only saves time for subsequent
+ maintenance or debugging, it more importantly aids in code reuse by
+ allowing a user to determine the safety and applicability of any
+ function for the problem at hand. As a result of such benefits, all
+ functions should contain the information presented in the addendum
+ section of this document.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S8" id="S8">4.2.6. Comment at the end of
+ braces if the content is more than one screen length</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Each closing brace should be followed on the same line by a
+ comment that describes the origination of the brace if the original
+ brace is off of the screen, or otherwise far away from the closing
+ brace. This will simplify the debugging, maintenance, and readability
+ of the code.</p>
+
+ <p>As a suggestion , use the following flags to make the comment and
+ its brace more readable:</p>
+
+ <p>use following a closing brace: } /* -END- if() or while () or
+ etc... */</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
if ( 1 == X )
{
do_something_very_important();
...some long list of commands...
} /* -END- if ( 1 == X ) */
</pre>
- </td>
- </tr>
- </table>
- </div>
+ </td>
+ </tr>
+ </table>
</div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="S9">4.3. Naming Conventions</a>
- </h2>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S10">4.3.1. Variable Names</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Use all lowercase, and separate words via an underscore ('_'). Do
- not start an identifier with an underscore. (ANSI C reserves
- these for use by the compiler and system headers.) Do not use
- identifiers which are reserved in ANSI C++. (E.g. template,
- class, true, false, ...). This is in case we ever decide to port
- Privoxy to C++.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </div>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="S9" id="S9">4.3. Naming Conventions</a></h2>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S10" id="S10">4.3.1. Variable
+ Names</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Use all lowercase, and separate words via an underscore ('_'). Do
+ not start an identifier with an underscore. (ANSI C reserves these
+ for use by the compiler and system headers.) Do not use identifiers
+ which are reserved in ANSI C++. (E.g. template, class, true, false,
+ ...). This is in case we ever decide to port Privoxy to C++.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
int ms_iis5_hack = 0;
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+
<pre class="PROGRAMLISTING">
int msiis5hack = 0; int msIis5Hack = 0;
</pre>
- </td>
- </tr>
- </table>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S11">4.3.2. Function Names</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Use all lowercase, and separate words via an underscore ('_'). Do
- not start an identifier with an underscore. (ANSI C reserves
- these for use by the compiler and system headers.) Do not use
- identifiers which are reserved in ANSI C++. (E.g. template,
- class, true, false, ...). This is in case we ever decide to port
- Privoxy to C++.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S11" id="S11">4.3.2. Function
+ Names</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Use all lowercase, and separate words via an underscore ('_'). Do
+ not start an identifier with an underscore. (ANSI C reserves these
+ for use by the compiler and system headers.) Do not use identifiers
+ which are reserved in ANSI C++. (E.g. template, class, true, false,
+ ...). This is in case we ever decide to port Privoxy to C++.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
int load_some_file( struct client_state *csp )
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+
<pre class="PROGRAMLISTING">
int loadsomefile( struct client_state *csp )
int loadSomeFile( struct client_state *csp )
</pre>
- </td>
- </tr>
- </table>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S12">4.3.3. Header file prototypes</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Use a descriptive parameter name in the function prototype in
- header files. Use the same parameter name in the header file that
- you use in the c file.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S12" id="S12">4.3.3. Header file
+ prototypes</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Use a descriptive parameter name in the function prototype in
+ header files. Use the same parameter name in the header file that you
+ use in the c file.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
(.h) extern int load_aclfile( struct client_state *csp );
(.c) int load_aclfile( struct client_state *csp )
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+
<pre class="PROGRAMLISTING">
(.h) extern int load_aclfile( struct client_state * ); or
(.h) extern int load_aclfile();
(.c) int load_aclfile( struct client_state *csp )
</pre>
- </td>
- </tr>
- </table>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S13">4.3.4. Enumerations, and #defines</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Use all capital letters, with underscores between words. Do not
- start an identifier with an underscore. (ANSI C reserves these
- for use by the compiler and system headers.)
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S13" id="S13">4.3.4. Enumerations, and
+ #defines</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Use all capital letters, with underscores between words. Do not
+ start an identifier with an underscore. (ANSI C reserves these for
+ use by the compiler and system headers.)</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
(enumeration) : enum Boolean { FALSE, TRUE };
(#define) : #define DEFAULT_SIZE 100;
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span> We
- have a standard naming scheme for #defines that toggle a feature
- in the preprocessor: FEATURE_>, where > is a short
- (preferably 1 or 2 word) description.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> We have a standard
+ naming scheme for #defines that toggle a feature in the preprocessor:
+ FEATURE_>, where > is a short (preferably 1 or 2 word)
+ description.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
#define FEATURE_FORCE 1
#ifdef FEATURE_FORCE
#define FORCE_PREFIX blah
#endif /* def FEATURE_FORCE */
</pre>
- </td>
- </tr>
- </table>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S14">4.3.5. Constants</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Spell common words out entirely (do not remove vowels).
- </p>
- <p>
- Use only widely-known domain acronyms and abbreviations.
- Capitalize all letters of an acronym.
- </p>
- <p>
- Use underscore (_) to separate adjacent acronyms and
- abbreviations. Never terminate a name with an underscore.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S14" id="S14">4.3.5. Constants</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Spell common words out entirely (do not remove vowels).</p>
+
+ <p>Use only widely-known domain acronyms and abbreviations.
+ Capitalize all letters of an acronym.</p>
+
+ <p>Use underscore (_) to separate adjacent acronyms and
+ abbreviations. Never terminate a name with an underscore.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
#define USE_IMAGE_LIST 1
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+
<pre class="PROGRAMLISTING">
#define USE_IMG_LST 1 or
#define _USE_IMAGE_LIST 1 or
#define USE_IMAGE_LIST_ 1 or
#define use_image_list 1 or
#define UseImageList 1
</pre>
- </td>
- </tr>
- </table>
- </div>
+ </td>
+ </tr>
+ </table>
</div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="S15">4.4. Using Space</a>
- </h2>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S16">4.4.1. Put braces on a line by themselves.</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- The brace needs to be on a line all by itself, not at the end of
- the statement. Curly braces should line up with the construct
- that they're associated with. This practice makes it easier to
- identify the opening and closing braces for a block.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </div>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="S15" id="S15">4.4. Using Space</a></h2>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S16" id="S16">4.4.1. Put braces on a line
+ by themselves.</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>The brace needs to be on a line all by itself, not at the end of
+ the statement. Curly braces should line up with the construct that
+ they're associated with. This practice makes it easier to identify
+ the opening and closing braces for a block.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
if ( this == that )
{
...
}
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
- </p>
- <p>
- if ( this == that ) { ... }
- </p>
- <p>
- or
- </p>
- <p>
- if ( this == that ) { ... }
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span> In
- the special case that the if-statement is inside a loop, and it
- is trivial, i.e. it tests for a condition that is obvious from
- the purpose of the block, one-liners as above may optically
- preserve the loop structure and make it easier to read.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Status:</i></span>
- developer-discretion.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example
- exception:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
+
+ <p>if ( this == that ) { ... }</p>
+
+ <p>or</p>
+
+ <p>if ( this == that ) { ... }</p>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> In the special
+ case that the if-statement is inside a loop, and it is trivial, i.e.
+ it tests for a condition that is obvious from the purpose of the
+ block, one-liners as above may optically preserve the loop structure
+ and make it easier to read.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Status:</span>
+ developer-discretion.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example exception:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
while ( more lines are read )
{
/* Please document what is/is not a comment line here */
do_something( line );
}
</pre>
- </td>
- </tr>
- </table>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S17">4.4.2. ALL control statements should have a
- block</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Using braces to make a block will make your code more readable
- and less prone to error. All control statements should have a
- block defined.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S17" id="S17">4.4.2. ALL control
+ statements should have a block</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Using braces to make a block will make your code more readable and
+ less prone to error. All control statements should have a block
+ defined.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
if ( this == that )
{
do_something();
do_something_else();
}
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
- </p>
- <p>
- if ( this == that ) do_something(); do_something_else();
- </p>
- <p>
- or
- </p>
- <p>
- if ( this == that ) do_something();
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span> The
- first example in "Instead of" will execute in a manner other than
- that which the developer desired (per indentation). Using code
- braces would have prevented this "feature". The "explanation" and
- "exception" from the point above also applies.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S18">4.4.3. Do not belabor/blow-up boolean
- expressions</a>
- </h3>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
+
+ <p>if ( this == that ) do_something(); do_something_else();</p>
+
+ <p>or</p>
+
+ <p>if ( this == that ) do_something();</p>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> The first example
+ in "Instead of" will execute in a manner other than that which the
+ developer desired (per indentation). Using code braces would have
+ prevented this "feature". The "explanation" and "exception" from the
+ point above also applies.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S18" id="S18">4.4.3. Do not
+ belabor/blow-up boolean expressions</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
structure->flag = ( condition );
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
- </p>
- <p>
- if ( condition ) { structure->flag = 1; } else {
- structure->flag = 0; }
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span> The
- former is readable and concise. The later is wordy and
- inefficient. Please assume that any developer new to the project
- has at least a "good" knowledge of C/C++. (Hope I do not offend
- by that last comment ... 8-)
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S19">4.4.4. Use white space freely because it is
- free</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Make it readable. The notable exception to using white space
- freely is listed in the next guideline.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
+
+ <p>if ( condition ) { structure->flag = 1; } else {
+ structure->flag = 0; }</p>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> The former is
+ readable and concise. The later is wordy and inefficient. Please
+ assume that any developer new to the project has at least a "good"
+ knowledge of C/C++. (Hope I do not offend by that last comment ...
+ 8-)</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S19" id="S19">4.4.4. Use white space
+ freely because it is free</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Make it readable. The notable exception to using white space
+ freely is listed in the next guideline.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
int first_value = 0;
int some_value = 0;
int another_value = 0;
first_value = old_value + ( ( some_value - another_value ) - whatever )
</pre>
- </td>
- </tr>
- </table>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S20">4.4.5. Don't use white space around structure
- operators</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- - structure pointer operator ( "->" ) - member operator ( "."
- ) - functions and parentheses
- </p>
- <p>
- It is a general coding practice to put pointers, references, and
- function parentheses next to names. With spaces, the connection
- between the object and variable/function name is not as clear.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S20" id="S20">4.4.5. Don't use white space
+ around structure operators</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>- structure pointer operator ( "->" ) - member operator ( "." )
+ - functions and parentheses</p>
+
+ <p>It is a general coding practice to put pointers, references, and
+ function parentheses next to names. With spaces, the connection
+ between the object and variable/function name is not as clear.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
a_struct->a_member;
a_struct.a_member;
function_name();
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
- a_struct -> a_member; a_struct . a_member; function_name ();
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S21">4.4.6. Make the last brace of a function stand
- out</a>
- </h3>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Instead of:</span> a_struct
+ -> a_member; a_struct . a_member; function_name ();</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S21" id="S21">4.4.6. Make the last brace
+ of a function stand out</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
int function1( ... )
{
...code...
{
} /* -END- function2 */
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
- </p>
- <p>
- int function1( ... ) { ...code... return( ret_code ); } int
- function2( ... ) { }
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span> Use 1
- blank line before the closing brace and 2 lines afterward. This
- makes the end of function standout to the most casual viewer.
- Although function comments help separate functions, this is still
- a good coding practice. In fact, I follow these rules when using
- blocks in "for", "while", "do" loops, and long if {} statements
- too. After all whitespace is free!
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Status:</i></span>
- developer-discretion on the number of blank lines. Enforced is
- the end of function comments.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S22">4.4.7. Use 3 character indentions</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- If some use 8 character TABs and some use 3 character TABs, the
- code can look *very* ragged. So use 3 character indentions only.
- If you like to use TABs, pass your code through a filter such as
- "expand -t3" before checking in your code.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
+
+ <p>int function1( ... ) { ...code... return( ret_code ); } int
+ function2( ... ) { }</p>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> Use 1 blank line
+ before the closing brace and 2 lines afterward. This makes the end of
+ function standout to the most casual viewer. Although function
+ comments help separate functions, this is still a good coding
+ practice. In fact, I follow these rules when using blocks in "for",
+ "while", "do" loops, and long if {} statements too. After all
+ whitespace is free!</p>
+
+ <p><span class="emphasis EMPHASIS c2">Status:</span>
+ developer-discretion on the number of blank lines. Enforced is the
+ end of function comments.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S22" id="S22">4.4.7. Use 3 character
+ indentions</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>If some use 8 character TABs and some use 3 character TABs, the
+ code can look *very* ragged. So use 3 character indentions only. If
+ you like to use TABs, pass your code through a filter such as "expand
+ -t3" before checking in your code.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
static const char * const url_code_map[256] =
{
NULL, ...
}
</pre>
- </td>
- </tr>
- </table>
- </div>
+ </td>
+ </tr>
+ </table>
</div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="S23">4.5. Initializing</a>
- </h2>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S24">4.5.1. Initialize all variables</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Do not assume that the variables declared will not be used until
- after they have been assigned a value somewhere else in the code.
- Remove the chance of accidentally using an unassigned variable.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </div>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="S23" id="S23">4.5. Initializing</a></h2>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S24" id="S24">4.5.1. Initialize all
+ variables</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Do not assume that the variables declared will not be used until
+ after they have been assigned a value somewhere else in the code.
+ Remove the chance of accidentally using an unassigned variable.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
short a_short = 0;
float a_float = 0;
struct *ptr = NULL;
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span> It is
- much easier to debug a SIGSEGV if the message says you are trying
- to access memory address 00000000 and not 129FA012; or
- array_ptr[20] causes a SIGSEV vs. array_ptr[0].
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Status:</i></span>
- developer-discretion if and only if the variable is assigned a
- value "shortly after" declaration.
- </p>
- </div>
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> It is much easier
+ to debug a SIGSEGV if the message says you are trying to access
+ memory address 00000000 and not 129FA012; or array_ptr[20] causes a
+ SIGSEV vs. array_ptr[0].</p>
+
+ <p><span class="emphasis EMPHASIS c2">Status:</span>
+ developer-discretion if and only if the variable is assigned a value
+ "shortly after" declaration.</p>
</div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="S25">4.6. Functions</a>
- </h2>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S26">4.6.1. Name functions that return a boolean as a
- question.</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Value should be phrased as a question that would logically be
- answered as a true or false statement
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </div>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="S25" id="S25">4.6. Functions</a></h2>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S26" id="S26">4.6.1. Name functions that
+ return a boolean as a question.</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Value should be phrased as a question that would logically be
+ answered as a true or false statement</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
should_we_block_this();
contains_an_image();
is_web_page_blank();
</pre>
- </td>
- </tr>
- </table>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S27">4.6.2. Always specify a return type for a
- function.</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- The default return for a function is an int. To avoid ambiguity,
- create a return for a function when the return has a purpose, and
- create a void return type if the function does not need to return
- anything.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S28">4.6.3. Minimize function calls when iterating by
- using variables</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- It is easy to write the following code, and a clear argument can
- be made that the code is easy to understand:
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S27" id="S27">4.6.2. Always specify a
+ return type for a function.</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>The default return for a function is an int. To avoid ambiguity,
+ create a return for a function when the return has a purpose, and
+ create a void return type if the function does not need to return
+ anything.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S28" id="S28">4.6.3. Minimize function
+ calls when iterating by using variables</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>It is easy to write the following code, and a clear argument can
+ be made that the code is easy to understand:</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
for ( size_t cnt = 0; cnt < block_list_length(); cnt++ )
{
....
}
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span>
- Unfortunately, this makes a function call for each and every
- iteration. This increases the overhead in the program, because
- the compiler has to look up the function each time, call it, and
- return a value. Depending on what occurs in the
- block_list_length() call, it might even be creating and
- destroying structures with each iteration, even though in each
- case it is comparing "cnt" to the same value, over and over.
- Remember too - even a call to block_list_length() is a function
- call, with the same overhead.
- </p>
- <p>
- Instead of using a function call during the iterations, assign
- the value to a variable, and evaluate using the variable.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> Unfortunately,
+ this makes a function call for each and every iteration. This
+ increases the overhead in the program, because the compiler has to
+ look up the function each time, call it, and return a value.
+ Depending on what occurs in the block_list_length() call, it might
+ even be creating and destroying structures with each iteration, even
+ though in each case it is comparing "cnt" to the same value, over and
+ over. Remember too - even a call to block_list_length() is a function
+ call, with the same overhead.</p>
+
+ <p>Instead of using a function call during the iterations, assign the
+ value to a variable, and evaluate using the variable.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
size_t len = block_list_length();
for ( size_t cnt = 0; cnt < len; cnt++ )
....
}
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Exceptions:</i></span>
- if the value of block_list_length() *may* change or could
- *potentially* change, then you must code the function call in the
- for/while loop.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S29">4.6.4. Pass and Return by Const Reference</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- This allows a developer to define a const pointer and call your
- function. If your function does not have the const keyword, we
- may not be able to use your function. Consider strcmp, if it were
- defined as: extern int strcmp( char *s1, char *s2 );
- </p>
- <p>
- I could then not use it to compare argv's in main: int main( int
- argc, const char *argv[] ) { strcmp( argv[0], "privoxy" ); }
- </p>
- <p>
- Both these pointers are *const*! If the c runtime library
- maintainers do it, we should too.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S30">4.6.5. Pass and Return by Value</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Most structures cannot fit onto a normal stack entry (i.e. they
- are not 4 bytes or less). Aka, a function declaration like: int
- load_aclfile( struct client_state csp )
- </p>
- <p>
- would not work. So, to be consistent, we should declare all
- prototypes with "pass by value": int load_aclfile( struct
- client_state *csp )
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S31">4.6.6. Names of include files</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Your include statements should contain the file name without a
- path. The path should be listed in the Makefile, using -I as
- processor directive to search the indicated paths. An exception
- to this would be for some proprietary software that utilizes a
- partial path to distinguish their header files from system or
- other header files.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Exceptions:</span> if the value
+ of block_list_length() *may* change or could *potentially* change,
+ then you must code the function call in the for/while loop.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S29" id="S29">4.6.4. Pass and Return by
+ Const Reference</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>This allows a developer to define a const pointer and call your
+ function. If your function does not have the const keyword, we may
+ not be able to use your function. Consider strcmp, if it were defined
+ as: extern int strcmp( char *s1, char *s2 );</p>
+
+ <p>I could then not use it to compare argv's in main: int main( int
+ argc, const char *argv[] ) { strcmp( argv[0], "privoxy" ); }</p>
+
+ <p>Both these pointers are *const*! If the c runtime library
+ maintainers do it, we should too.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S30" id="S30">4.6.5. Pass and Return by
+ Value</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Most structures cannot fit onto a normal stack entry (i.e. they
+ are not 4 bytes or less). Aka, a function declaration like: int
+ load_aclfile( struct client_state csp )</p>
+
+ <p>would not work. So, to be consistent, we should declare all
+ prototypes with "pass by value": int load_aclfile( struct
+ client_state *csp )</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S31" id="S31">4.6.6. Names of include
+ files</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Your include statements should contain the file name without a
+ path. The path should be listed in the Makefile, using -I as
+ processor directive to search the indicated paths. An exception to
+ this would be for some proprietary software that utilizes a partial
+ path to distinguish their header files from system or other header
+ files.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
#include <iostream.h> /* This is not a local include */
#include "config.h" /* This IS a local include */
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Exception:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Exception:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+
<pre class="PROGRAMLISTING">
/* This is not a local include, but requires a path element. */
#include <sys/fileName.h>
</pre>
- </td>
- </tr>
- </table>
-
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span>
- Please! do not add "-I." to the Makefile without a _very_ good
- reason. This duplicates the #include "file.h" behavior.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S32">4.6.7. Provide multiple inclusion protection</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Prevents compiler and linker errors resulting from redefinition
- of items.
- </p>
- <p>
- Wrap each header file with the following syntax to prevent
- multiple inclusions of the file. Of course, replace PROJECT_H
- with your file name, with "." Changed to "_", and make it
- uppercase.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> Please! do not add
+ "-I." to the Makefile without a _very_ good reason. This duplicates
+ the #include "file.h" behavior.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S32" id="S32">4.6.7. Provide multiple
+ inclusion protection</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Prevents compiler and linker errors resulting from redefinition of
+ items.</p>
+
+ <p>Wrap each header file with the following syntax to prevent
+ multiple inclusions of the file. Of course, replace PROJECT_H with
+ your file name, with "." Changed to "_", and make it uppercase.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
#ifndef PROJECT_H_INCLUDED
#define PROJECT_H_INCLUDED
...
#endif /* ndef PROJECT_H_INCLUDED */
</pre>
- </td>
- </tr>
- </table>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S33">4.6.8. Use `extern "C"` when appropriate</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- If our headers are included from C++, they must declare our
- functions as `extern "C"`. This has no cost in C, but increases
- the potential re-usability of our code.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S33" id="S33">4.6.8. Use `extern "C"` when
+ appropriate</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>If our headers are included from C++, they must declare our
+ functions as `extern "C"`. This has no cost in C, but increases the
+ potential re-usability of our code.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
#ifdef __cplusplus
extern "C"
{
}
#endif /* def __cplusplus */
</pre>
- </td>
- </tr>
- </table>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S34">4.6.9. Where Possible, Use Forward Struct
- Declaration Instead of Includes</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Useful in headers that include pointers to other struct's.
- Modifications to excess header files may cause needless compiles.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S34" id="S34">4.6.9. Where Possible, Use
+ Forward Struct Declaration Instead of Includes</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Useful in headers that include pointers to other struct's.
+ Modifications to excess header files may cause needless compiles.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
/*********************************************************************
* We're avoiding an include statement here!
*********************************************************************/
struct file_list;
extern file_list *xyz;
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span> If
- you declare "file_list xyz;" (without the pointer), then
- including the proper header file is necessary. If you only want
- to prototype a pointer, however, the header file is unnecessary.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Status:</i></span> Use
- with discretion.
- </p>
- </div>
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> If you declare
+ "file_list xyz;" (without the pointer), then including the proper
+ header file is necessary. If you only want to prototype a pointer,
+ however, the header file is unnecessary.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Status:</span> Use with
+ discretion.</p>
</div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="S35">4.7. General Coding Practices</a>
- </h2>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S36">4.7.1. Turn on warnings</a>
- </h3>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Explanation</i></span>
- </p>
- <p>
- Compiler warnings are meant to help you find bugs. You should
- turn on as many as possible. With GCC, the switch is "-Wall". Try
- and fix as many warnings as possible.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S37">4.7.2. Provide a default case for all switch
- statements</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- What you think is guaranteed is never really guaranteed. The
- value that you don't think you need to check is the one that
- someday will be passed. So, to protect yourself from the unknown,
- always have a default step in a switch statement.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </div>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="S35" id="S35">4.7. General Coding
+ Practices</a></h2>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S36" id="S36">4.7.1. Turn on
+ warnings</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation</span></p>
+
+ <p>Compiler warnings are meant to help you find bugs. You should turn
+ on as many as possible. With GCC, the switch is "-Wall". Try and fix
+ as many warnings as possible.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S37" id="S37">4.7.2. Provide a default
+ case for all switch statements</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>What you think is guaranteed is never really guaranteed. The value
+ that you don't think you need to check is the one that someday will
+ be passed. So, to protect yourself from the unknown, always have a
+ default step in a switch statement.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
switch( hash_string( cmd ) )
{
case hash_actions_file :
} /* end switch( hash_string( cmd ) ) */
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span> If
- you already have a default condition, you are obviously exempt
- from this point. Of note, most of the WIN32 code calls
- `DefWindowProc' after the switch statement. This API call
- *should* be included in a default statement.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Another
- Note:</i></span> This is not so much a readability issue as a
- robust programming issue. The "anomaly code goes here" may be no
- more than a print to the STDERR stream (as in load_config). Or it
- may really be an abort condition.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Status:</i></span>
- Programmer discretion is advised.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S38">4.7.3. Try to avoid falling through cases in a
- switch statement.</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- In general, you will want to have a 'break' statement within each
- 'case' of a switch statement. This allows for the code to be more
- readable and understandable, and furthermore can prevent unwanted
- surprises if someone else later gets creative and moves the code
- around.
- </p>
- <p>
- The language allows you to plan the fall through from one case
- statement to another simply by omitting the break statement
- within the case statement. This feature does have benefits, but
- should only be used in rare cases. In general, use a break
- statement for each case statement.
- </p>
- <p>
- If you choose to allow fall through, you should comment both the
- fact of the fall through and reason why you felt it was
- necessary.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S39">4.7.4. Use 'long' or 'short' Instead of 'int'</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- On 32-bit platforms, int usually has the range of long. On 16-bit
- platforms, int has the range of short.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Status:</i></span>
- open-to-debate. In the case of most FSF projects (including
- X/GNU-Emacs), there are typedefs to int4, int8, int16, (or
- equivalence ... I forget the exact typedefs now). Should we add
- these to IJB now that we have a "configure" script?
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S40">4.7.5. Don't mix size_t and other types</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- The type of size_t varies across platforms. Do not make
- assumptions about whether it is signed or unsigned, or about how
- long it is. Do not compare a size_t against another variable of a
- different type (or even against a constant) without casting one
- of the values.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S41">4.7.6. Declare each variable and struct on its own
- line.</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- It can be tempting to declare a series of variables all on one
- line. Don't.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> If you already
+ have a default condition, you are obviously exempt from this point.
+ Of note, most of the WIN32 code calls `DefWindowProc' after the
+ switch statement. This API call *should* be included in a default
+ statement.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Another Note:</span> This is
+ not so much a readability issue as a robust programming issue. The
+ "anomaly code goes here" may be no more than a print to the STDERR
+ stream (as in load_config). Or it may really be an abort
+ condition.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Status:</span> Programmer
+ discretion is advised.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S38" id="S38">4.7.3. Try to avoid falling
+ through cases in a switch statement.</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>In general, you will want to have a 'break' statement within each
+ 'case' of a switch statement. This allows for the code to be more
+ readable and understandable, and furthermore can prevent unwanted
+ surprises if someone else later gets creative and moves the code
+ around.</p>
+
+ <p>The language allows you to plan the fall through from one case
+ statement to another simply by omitting the break statement within
+ the case statement. This feature does have benefits, but should only
+ be used in rare cases. In general, use a break statement for each
+ case statement.</p>
+
+ <p>If you choose to allow fall through, you should comment both the
+ fact of the fall through and reason why you felt it was
+ necessary.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S39" id="S39">4.7.4. Use 'long' or 'short'
+ Instead of 'int'</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>On 32-bit platforms, int usually has the range of long. On 16-bit
+ platforms, int has the range of short.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Status:</span> open-to-debate.
+ In the case of most FSF projects (including X/GNU-Emacs), there are
+ typedefs to int4, int8, int16, (or equivalence ... I forget the exact
+ typedefs now). Should we add these to IJB now that we have a
+ "configure" script?</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S40" id="S40">4.7.5. Don't mix size_t and
+ other types</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>The type of size_t varies across platforms. Do not make
+ assumptions about whether it is signed or unsigned, or about how long
+ it is. Do not compare a size_t against another variable of a
+ different type (or even against a constant) without casting one of
+ the values.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S41" id="S41">4.7.6. Declare each variable
+ and struct on its own line.</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>It can be tempting to declare a series of variables all on one
+ line. Don't.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
long a = 0;
long b = 0;
long c = 0;
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
- </p>
- <p>
- long a, b, c;
- </p>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span> - there is more room for
- comments on the individual variables - easier to add new
- variables without messing up the original ones - when searching
- on a variable to find its type, there is less clutter to
- "visually" eliminate
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Exceptions:</i></span>
- when you want to declare a bunch of loop variables or other
- trivial variables; feel free to declare them on one line. You
- should, although, provide a good comment on their functions.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Status:</i></span>
- developer-discretion.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S42">4.7.7. Use malloc/zalloc sparingly</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- Create a local struct (on the stack) if the variable will live
- and die within the context of one function call.
- </p>
- <p>
- Only "malloc" a struct (on the heap) if the variable's life will
- extend beyond the context of one function call.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
+
+ <p>long a, b, c;</p>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span> - there is
+ more room for comments on the individual variables - easier to add
+ new variables without messing up the original ones - when searching
+ on a variable to find its type, there is less clutter to "visually"
+ eliminate</p>
+
+ <p><span class="emphasis EMPHASIS c2">Exceptions:</span> when you
+ want to declare a bunch of loop variables or other trivial variables;
+ feel free to declare them on one line. You should, although, provide
+ a good comment on their functions.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Status:</span>
+ developer-discretion.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S42" id="S42">4.7.7. Use malloc/zalloc
+ sparingly</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>Create a local struct (on the stack) if the variable will live and
+ die within the context of one function call.</p>
+
+ <p>Only "malloc" a struct (on the heap) if the variable's life will
+ extend beyond the context of one function call.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
If a function creates a struct and stores a pointer to it in a
list, then it should definitely be allocated via `malloc'.
</pre>
- </td>
- </tr>
- </table>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S43">4.7.8. The Programmer Who Uses 'malloc' is
- Responsible for Ensuring 'free'</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- If you have to "malloc" an instance, you are responsible for
- insuring that the instance is `free'd, even if the deallocation
- event falls within some other programmer's code. You are also
- responsible for ensuring that deletion is timely (i.e. not too
- soon, not too late). This is known as "low-coupling" and is a
- "good thing (tm)". You may need to offer a free/unload/destructor
- type function to accommodate this.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S43" id="S43">4.7.8. The Programmer Who
+ Uses 'malloc' is Responsible for Ensuring 'free'</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>If you have to "malloc" an instance, you are responsible for
+ insuring that the instance is `free'd, even if the deallocation event
+ falls within some other programmer's code. You are also responsible
+ for ensuring that deletion is timely (i.e. not too soon, not too
+ late). This is known as "low-coupling" and is a "good thing (tm)".
+ You may need to offer a free/unload/destructor type function to
+ accommodate this.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
int load_re_filterfile( struct client_state *csp ) { ... }
static void unload_re_filterfile( void *f ) { ... }
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Exceptions:</i></span>
- </p>
- <p>
- The developer cannot be expected to provide `free'ing functions
- for C run-time library functions ... such as `strdup'.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Status:</i></span>
- developer-discretion. The "main" use of this standard is for
- allocating and freeing data structures (complex or nested).
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S44">4.7.9. Add loaders to the `file_list' structure and
- in order</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- I have ordered all of the "blocker" file code to be in alpha
- order. It is easier to add/read new blockers when you expect a
- certain order.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span> It
- may appear that the alpha order is broken in places by POPUP
- tests coming before PCRS tests. But since POPUPs can also be
- referred to as KILLPOPUPs, it is clear that it should come first.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="S45">4.7.10. "Uncertain" new code and/or changes to
- existing code, use FIXME or XXX</a>
- </h3>
- <p>
- <span class="emphasis"><i class=
- "EMPHASIS">Explanation:</i></span>
- </p>
- <p>
- If you have enough confidence in new code or confidence in your
- changes, but are not *quite* sure of the repercussions, add this:
- </p>
- <p>
- /* FIXME: this code has a logic error on platform XYZ, *
- attempting to fix */ #ifdef PLATFORM ...changed code here...
- #endif
- </p>
- <p>
- or:
- </p>
- <p>
- /* FIXME: I think the original author really meant this... */
- ...changed code here...
- </p>
- <p>
- or:
- </p>
- <p>
- /* FIXME: new code that *may* break something else... */ ...new
- code here...
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span> If
- you make it clear that this may or may not be a "good thing
- (tm)", it will be easier to identify and include in the project
- (or conversely exclude from the project).
- </p>
- </div>
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Exceptions:</span></p>
+
+ <p>The developer cannot be expected to provide `free'ing functions
+ for C run-time library functions ... such as `strdup'.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Status:</span>
+ developer-discretion. The "main" use of this standard is for
+ allocating and freeing data structures (complex or nested).</p>
</div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="S46">4.8. Addendum: Template for files and function
- comment blocks:</a>
- </h2>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example for file
- comments:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
-const char FILENAME_rcs[] = "$Id: coding.html,v 1.54 2010/11/13 12:50:18 fabiankeil Exp $";
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S44" id="S44">4.7.9. Add loaders to the
+ `file_list' structure and in order</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>I have ordered all of the "blocker" file code to be in alpha
+ order. It is easier to add/read new blockers when you expect a
+ certain order.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> It may appear that
+ the alpha order is broken in places by POPUP tests coming before PCRS
+ tests. But since POPUPs can also be referred to as KILLPOPUPs, it is
+ clear that it should come first.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S45" id="S45">4.7.10. "Uncertain" new code
+ and/or changes to existing code, use FIXME or XXX</a></h3>
+
+ <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
+
+ <p>If you have enough confidence in new code or confidence in your
+ changes, but are not *quite* sure of the repercussions, add this:</p>
+
+ <p>/* FIXME: this code has a logic error on platform XYZ, *
+ attempting to fix */ #ifdef PLATFORM ...changed code here...
+ #endif</p>
+
+ <p>or:</p>
+
+ <p>/* FIXME: I think the original author really meant this... */
+ ...changed code here...</p>
+
+ <p>or:</p>
+
+ <p>/* FIXME: new code that *may* break something else... */ ...new
+ code here...</p>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> If you make it
+ clear that this may or may not be a "good thing (tm)", it will be
+ easier to identify and include in the project (or conversely exclude
+ from the project).</p>
+ </div>
+ </div>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="S46" id="S46">4.8. Addendum: Template for
+ files and function comment blocks:</a></h2>
+
+ <p><span class="emphasis EMPHASIS c2">Example for file
+ comments:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+const char FILENAME_rcs[] = "$Id$";
/*********************************************************************
*
- * File : $Source: /cvsroot/ijbswa/current/doc/webserver/developer-manual/coding.html,v $
+ * File : $Source$
*
* Purpose : (Fill me in with a good description!)
*
const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span> This
- declares the rcs variables that should be added to the
- "show-proxy-args" page. If this is a brand new creation by you, you
- are free to change the "Copyright" section to represent the rights
- you wish to maintain.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span> The
- formfeed character that is present right after the comment flower
- box is handy for (X|GNU)Emacs users to skip the verbiage and get to
- the heart of the code (via `forward-page' and `backward-page').
- Please include it if you can.
- </p>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example for file header
- comments:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> This declares the
+ rcs variables that should be added to the "show-proxy-args" page. If
+ this is a brand new creation by you, you are free to change the
+ "Copyright" section to represent the rights you wish to maintain.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> The formfeed
+ character that is present right after the comment flower box is handy
+ for (X|GNU)Emacs users to skip the verbiage and get to the heart of the
+ code (via `forward-page' and `backward-page'). Please include it if you
+ can.</p>
+
+ <p><span class="emphasis EMPHASIS c2">Example for file header
+ comments:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: coding.html,v 1.54 2010/11/13 12:50:18 fabiankeil Exp $"
+#define FILENAME_H_VERSION "$Id$"
/*********************************************************************
*
- * File : $Source: /cvsroot/ijbswa/current/doc/webserver/developer-manual/coding.html,v $
+ * File : $Source$
*
* Purpose : (Fill me in with a good description!)
*
end:
*/
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Example for function
- comments:</i></span>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis EMPHASIS c2">Example for function
+ comments:</span></p>
+
+ <table class="c3" border="0" width="100%">
+ <tr>
+ <td>
+
<pre class="PROGRAMLISTING">
/*********************************************************************
*
* Function : FUNCTION_NAME
}
</pre>
- </td>
- </tr>
- </table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Note:</i></span> If we
- all follow this practice, we should be able to parse our code to
- create a "self-documenting" web page.
- </p>
- </div>
- </div>
- <div class="NAVFOOTER">
- <hr width="100%" class="c1">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
- <tr>
- <td width="33%" align="left" valign="top">
- <a href="documentation.html" accesskey="P">Prev</a>
- </td>
- <td width="34%" align="center" valign="top">
- <a href="index.html" accesskey="H">Home</a>
- </td>
- <td width="33%" align="right" valign="top">
- <a href="testing.html" accesskey="N">Next</a>
- </td>
- </tr>
- <tr>
- <td width="33%" align="left" valign="top">
- Documentation Guidelines
- </td>
- <td width="34%" align="center" valign="top">
-
- </td>
- <td width="33%" align="right" valign="top">
- Testing Guidelines
</td>
</tr>
</table>
+
+ <p><span class="emphasis EMPHASIS c2">Note:</span> If we all follow
+ this practice, we should be able to parse our code to create a
+ "self-documenting" web page.</p>
</div>
- </body>
-</html>
+ </div>
+
+ <div class="NAVFOOTER">
+ <hr class="c1" width="100%">
+
+ <table summary="Footer navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <td width="33%" align="left" valign="top"><a href=
+ "documentation.html" accesskey="P">Prev</a></td>
+
+ <td width="34%" align="center" valign="top"><a href="index.html"
+ accesskey="H">Home</a></td>
+ <td width="33%" align="right" valign="top"><a href="testing.html"
+ accesskey="N">Next</a></td>
+ </tr>
+
+ <tr>
+ <td width="33%" align="left" valign="top">Documentation
+ Guidelines</td>
+
+ <td width="34%" align="center" valign="top"> </td>
+
+ <td width="33%" align="right" valign="top">Testing Guidelines</td>
+ </tr>
+ </table>
+ </div>
+</body>
+</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
-Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+"http://www.w3.org/TR/html4/loose.dtd">
+
<html>
- <head>
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>
- Contacting the developers, Bug Reporting and Feature Requests
- </title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
- <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
- <link rel="PREVIOUS" title="Update the Webserver" href=
- "webserver-update.html">
- <link rel="NEXT" title="Privoxy Copyright, License and History" href=
- "copyright.html">
- <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<style type="text/css">
- body {
+<head>
+ <meta name="generator" content=
+ "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
+
+ <title>Contacting the developers, Bug Reporting and Feature
+ Requests</title>
+ <meta name="GENERATOR" content=
+ "Modular DocBook HTML Stylesheet Version 1.79">
+ <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
+ <link rel="PREVIOUS" title="Update the Webserver" href=
+ "webserver-update.html">
+ <link rel="NEXT" title="Privoxy Copyright, License and History" href=
+ "copyright.html">
+ <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+ <style type="text/css">
+body {
background-color: #EEEEEE;
color: #000000;
- }
- :link { color: #0000FF }
- :visited { color: #840084 }
- :active { color: #0000FF }
- hr.c1 {text-align: left}
-</style>
- </head>
- <body class="SECT1">
- <div class="NAVHEADER">
- <table summary="Header navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
- <tr>
- <th colspan="3" align="center">
- Privoxy Developer Manual
- </th>
- </tr>
- <tr>
- <td width="10%" align="left" valign="bottom">
- <a href="webserver-update.html" accesskey="P">Prev</a>
- </td>
- <td width="80%" align="center" valign="bottom">
- </td>
- <td width="10%" align="right" valign="bottom">
- <a href="copyright.html" accesskey="N">Next</a>
- </td>
- </tr>
- </table>
- <hr width="100%" class="c1">
+ }
+ :link { color: #0000FF }
+ :visited { color: #840084 }
+ :active { color: #0000FF }
+ span.c2 {font-style: italic}
+ hr.c1 {text-align: left}
+ </style>
+</head>
+
+<body class="SECT1">
+ <div class="NAVHEADER">
+ <table summary="Header navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <th colspan="3" align="center">Privoxy Developer Manual</th>
+ </tr>
+
+ <tr>
+ <td width="10%" align="left" valign="bottom"><a href=
+ "webserver-update.html" accesskey="P">Prev</a></td>
+
+ <td width="80%" align="center" valign="bottom"></td>
+
+ <td width="10%" align="right" valign="bottom"><a href=
+ "copyright.html" accesskey="N">Next</a></td>
+ </tr>
+ </table>
+ <hr class="c1" width="100%">
+ </div>
+
+ <div class="SECT1">
+ <h1 class="SECT1"><a name="CONTACT" id="CONTACT">8. Contacting the
+ developers, Bug Reporting and Feature Requests</a></h1>
+
+ <p>We value your feedback. In fact, we rely on it to improve <span class=
+ "APPLICATION">Privoxy</span> and its configuration. However, please note
+ the following hints, so we can provide you with the best support:</p>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="CONTACT-SUPPORT" id="CONTACT-SUPPORT">8.1.
+ Get Support</a></h2>
+
+ <p>For casual users, our <a href=
+ "http://sourceforge.net/tracker/?group_id=11118&atid=211118"
+ target="_top">support forum at SourceForge</a> is probably best suited:
+ <a href=
+ "http://sourceforge.net/tracker/?group_id=11118&atid=211118"
+ target="_top">http://sourceforge.net/tracker/?group_id=11118&atid=211118</a></p>
+
+ <p>All users are of course welcome to discuss their issues on the
+ <a href="http://lists.sourceforge.net/lists/listinfo/ijbswa-users"
+ target="_top">users mailing list</a>, where the developers also hang
+ around.</p>
+
+ <p>Please don't sent private support requests to individual Privoxy
+ developers, either use the mailing lists or the support trackers.</p>
+
+ <p>If you have to contact a Privoxy developer directly for other
+ reasons, please send a real mail and do not bother with SourceForge's
+ messaging system. Answers to SourceForge messages are usually bounced
+ by SourceForge's mail server in which case the developer wasted time
+ writing a response you don't get. From your point of view it will look
+ like your message has been completely ignored, so this is frustrating
+ for all parties involved.</p>
+
+ <p>Note that the Privoxy mailing lists are moderated. Posts from
+ unsubscribed addresses have to be accepted manually by a moderator.
+ This may cause a delay of several days and if you use a subject that
+ doesn't clearly mention Privoxy or one of its features, your message
+ may be accidentally discarded as spam.</p>
+
+ <p>If you aren't subscribed, you should therefore spend a few seconds
+ to come up with a proper subject. Additionally you should make it clear
+ that you want to get CC'd. Otherwise some responses will be directed to
+ the mailing list only, and you won't see them.</p>
</div>
- <div class="SECT1">
- <h1 class="SECT1">
- <a name="CONTACT">8. Contacting the developers, Bug Reporting and
- Feature Requests</a>
- </h1>
- <p>
- We value your feedback. In fact, we rely on it to improve <span
- class="APPLICATION">Privoxy</span> and its configuration. However,
- please note the following hints, so we can provide you with the best
- support:
- </p>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="CONTACT-SUPPORT">8.1. Get Support</a>
- </h2>
- <p>
- For casual users, our <a href=
- "http://sourceforge.net/tracker/?group_id=11118&atid=211118"
- target="_top">support forum at SourceForge</a> is probably best
- suited: <a href=
- "http://sourceforge.net/tracker/?group_id=11118&atid=211118"
- target=
- "_top">http://sourceforge.net/tracker/?group_id=11118&atid=211118</a>
- </p>
- <p>
- All users are of course welcome to discuss their issues on the <a
- href="http://lists.sourceforge.net/lists/listinfo/ijbswa-users"
- target="_top">users mailing list</a>, where the developers also
- hang around.
- </p>
- <p>
- Please don't sent private support requests to individual Privoxy
- developers, either use the mailing lists or the support trackers.
- </p>
- <p>
- If you have to contact a Privoxy developer directly for other
- reasons, please send a real mail and do not bother with
- SourceForge's messaging system. Answers to SourceForge messages are
- usually bounced by SourceForge's mail server in which case the
- developer wasted time writing a response you don't get. From your
- point of view it will look like your message has been completely
- ignored, so this is frustrating for all parties involved.
- </p>
- <p>
- Note that the Privoxy mailing lists are moderated. Posts from
- unsubscribed addresses have to be accepted manually by a moderator.
- This may cause a delay of several days and if you use a subject
- that doesn't clearly mention Privoxy or one of its features, your
- message may be accidentally discarded as spam.
- </p>
- <p>
- If you aren't subscribed, you should therefore spend a few seconds
- to come up with a proper subject. Additionally you should make it
- clear that you want to get CC'd. Otherwise some responses will be
- directed to the mailing list only, and you won't see them.
- </p>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="REPORTING" id="REPORTING">8.2. Reporting
+ Problems</a></h2>
+
+ <p><span class="QUOTE">"Problems"</span> for our purposes, come in two
+ forms:</p>
+
+ <ul>
+ <li>
+ <p>Configuration issues, such as ads that slip through, or sites
+ that don't function properly due to one <span class=
+ "APPLICATION">Privoxy</span> <span class="QUOTE">"action"</span> or
+ another being turned <span class="QUOTE">"on"</span>.</p>
+ </li>
+
+ <li>
+ <p><span class="QUOTE">"Bugs"</span> in the programming code that
+ makes up <span class="APPLICATION">Privoxy</span>, such as that
+ might cause a crash.</p>
+ </li>
+ </ul>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="CONTACT-ADS" id="CONTACT-ADS">8.2.1.
+ Reporting Ads or Other Configuration Problems</a></h3>
+
+ <p>Please send feedback on ads that slipped through, innocent images
+ that were blocked, sites that don't work properly, and other
+ configuration related problem of <tt class=
+ "FILENAME">default.action</tt> file, to <a href=
+ "http://sourceforge.net/tracker/?group_id=11118&atid=460288"
+ target=
+ "_top">http://sourceforge.net/tracker/?group_id=11118&atid=460288</a>,
+ the Actions File Tracker.</p>
+
+ <p>New, improved <tt class="FILENAME">default.action</tt> files may
+ occasionally be made available based on your feedback. These will be
+ announced on the <a href=
+ "http://lists.sourceforge.net/lists/listinfo/ijbswa-announce" target=
+ "_top">ijbswa-announce</a> list and available from our the <a href=
+ "http://sourceforge.net/project/showfiles.php?group_id=11118" target=
+ "_top">files section</a> of our <a href=
+ "http://sf.net/projects/ijbswa/" target="_top">project page</a>.</p>
</div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="REPORTING">8.2. Reporting Problems</a>
- </h2>
- <p>
- <span class="QUOTE">"Problems"</span> for our purposes, come in two
- forms:
- </p>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="CONTACT-BUGS" id="CONTACT-BUGS">8.2.2.
+ Reporting Bugs</a></h3>
+
+ <p>Please report all bugs through our bug tracker: <a href=
+ "http://sourceforge.net/tracker/?group_id=11118&atid=111118"
+ target=
+ "_top">http://sourceforge.net/tracker/?group_id=11118&atid=111118</a>.</p>
+
+ <p>Before doing so, please make sure that the bug has <span class=
+ "emphasis EMPHASIS c2">not already been submitted</span> and observe
+ the additional hints at the top of the <a href=
+ "http://sourceforge.net/tracker/?func=add&group_id=11118&atid=111118"
+ target="_top">submit form</a>. If already submitted, please feel free
+ to add any info to the original report that might help to solve the
+ issue.</p>
+
+ <p>Please try to verify that it is a <span class=
+ "APPLICATION">Privoxy</span> bug, and not a browser or site bug or
+ documented behaviour that just happens to be different than what you
+ expected. If unsure, try <a href=
+ "http://config.privoxy.org/toggle?set=disable" target="_top">toggling
+ off</a> <span class="APPLICATION">Privoxy</span>, and see if the
+ problem persists.</p>
+
+ <p>If you are using your own custom configuration, please try the
+ stock configs to see if the problem is configuration related. If
+ you're having problems with a feature that is disabled by default,
+ please ask around on the mailing list if others can reproduce the
+ problem.</p>
+
+ <p>If you aren't using the latest Privoxy version, the bug may have
+ been found and fixed in the meantime. We would appreciate if you
+ could take the time to <a href=
+ "http://www.privoxy.org/user-manual/installation.html" target=
+ "_top">upgrade to the latest version</a> (or even the latest CVS
+ snapshot) and verify that your bug still exists.</p>
+
+ <p>Please be sure to provide the following information:</p>
+
<ul>
<li>
- <p>
- Configuration issues, such as ads that slip through, or sites
- that don't function properly due to one <span class=
- "APPLICATION">Privoxy</span> <span class=
- "QUOTE">"action"</span> or another being turned <span class=
- "QUOTE">"on"</span>.
- </p>
+ <p>The exact <span class="APPLICATION">Privoxy</span> version you
+ are using (if you got the source from CVS, please also provide
+ the source code revisions as shown in <a href=
+ "http://config.privoxy.org/show-version" target=
+ "_top">http://config.privoxy.org/show-version</a>).</p>
+ </li>
+
+ <li>
+ <p>The operating system and versions you run <span class=
+ "APPLICATION">Privoxy</span> on, (e.g. <span class=
+ "APPLICATION">Windows XP SP2</span>), if you are using a Unix
+ flavor, sending the output of <span class="QUOTE">"uname
+ -a"</span> should do, in case of GNU/Linux, please also name the
+ distribution.</p>
+ </li>
+
+ <li>
+ <p>The name, platform, and version of the <span class=
+ "APPLICATION">browser</span> you were using (e.g. <span class=
+ "APPLICATION">Internet Explorer v5.5</span> for Mac).</p>
+ </li>
+
+ <li>
+ <p>The URL where the problem occurred, or some way for us to
+ duplicate the problem (e.g. <tt class=
+ "LITERAL">http://somesite.example.com/?somethingelse=123</tt>).</p>
+ </li>
+
+ <li>
+ <p>Whether your version of <span class=
+ "APPLICATION">Privoxy</span> is one supplied by the <span class=
+ "APPLICATION">Privoxy</span> developers via SourceForge, or if
+ you got your copy somewhere else.</p>
+ </li>
+
+ <li>
+ <p>Whether you are using <span class="APPLICATION">Privoxy</span>
+ in tandem with another proxy such as <span class=
+ "APPLICATION">Tor</span>. If so, please temporary disable the
+ other proxy to see if the symptoms change.</p>
</li>
+
<li>
- <p>
- <span class="QUOTE">"Bugs"</span> in the programming code that
- makes up <span class="APPLICATION">Privoxy</span>, such as that
- might cause a crash.
- </p>
+ <p>Whether you are using a personal firewall product. If so, does
+ <span class="APPLICATION">Privoxy</span> work without it?</p>
+ </li>
+
+ <li>
+ <p>Any other pertinent information to help identify the problem
+ such as config or log file excerpts (yes, you should have log
+ file entries for each action taken). To get a meaningful logfile,
+ please make sure that the <a href=
+ "../user-manual/config.html#LOGFILE" target="_top">logfile
+ directive</a> is being used and the following <a href=
+ "../user-manual/config.html#DEBUG" target="_top">debug
+ options</a> are enabled:</p>
+
+ <p class="LITERALLAYOUT">
+ debug 1 # Log the destination for each request Privoxy let through. See also debug 1024.<br>
+
+ debug 2 # show each connection status<br>
+
+ debug 4 # show I/O status<br>
+
+ debug 8 # show header parsing<br>
+
+ debug 128 # debug redirects<br>
+ debug 256 # debug GIF de-animation<br>
+
+ debug 512 # Common Log Format<br>
+
+ debug 1024 # Log the destination for requests Privoxy didn't let through, and the reason why.<br>
+
+ debug 4096 # Startup banner and warnings.<br>
+
+ debug 8192 # Non-fatal errors</p>If you
+ are having trouble with a filter, please additionally enable
+
+ <p class="LITERALLAYOUT">
+ debug 64 # debug regular expression filters</p>If
+ you are using Privoxy 3.0.17 or later and suspect that it
+ interprets the request or the response incorrectly, please enable
+
+ <p class="LITERALLAYOUT">
+ debug 32768 # log all data read from the network</p>Note
+ that Privoxy log files may contain sensitive information so
+ please don't submit any logfiles you didn't read first. You can
+ mask sensitive information as long as it's clear that you removed
+ something.
</li>
</ul>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="CONTACT-ADS">8.2.1. Reporting Ads or Other Configuration
- Problems</a>
- </h3>
- <p>
- Please send feedback on ads that slipped through, innocent images
- that were blocked, sites that don't work properly, and other
- configuration related problem of <tt class=
- "FILENAME">default.action</tt> file, to <a href=
- "http://sourceforge.net/tracker/?group_id=11118&atid=460288"
- target=
- "_top">http://sourceforge.net/tracker/?group_id=11118&atid=460288</a>,
- the Actions File Tracker.
- </p>
- <p>
- New, improved <tt class="FILENAME">default.action</tt> files may
- occasionally be made available based on your feedback. These will
- be announced on the <a href=
- "http://lists.sourceforge.net/lists/listinfo/ijbswa-announce"
- target="_top">ijbswa-announce</a> list and available from our the
- <a href=
- "http://sourceforge.net/project/showfiles.php?group_id=11118"
- target="_top">files section</a> of our <a href=
- "http://sf.net/projects/ijbswa/" target="_top">project page</a>.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="CONTACT-BUGS">8.2.2. Reporting Bugs</a>
- </h3>
- <p>
- Please report all bugs through our bug tracker: <a href=
- "http://sourceforge.net/tracker/?group_id=11118&atid=111118"
- target=
- "_top">http://sourceforge.net/tracker/?group_id=11118&atid=111118</a>.
- </p>
- <p>
- Before doing so, please make sure that the bug has <span class=
- "emphasis"><i class="EMPHASIS">not already been
- submitted</i></span> and observe the additional hints at the top
- of the <a href=
- "http://sourceforge.net/tracker/?func=add&group_id=11118&atid=111118"
- target="_top">submit form</a>. If already submitted, please feel
- free to add any info to the original report that might help to
- solve the issue.
- </p>
- <p>
- Please try to verify that it is a <span class=
- "APPLICATION">Privoxy</span> bug, and not a browser or site bug
- or documented behaviour that just happens to be different than
- what you expected. If unsure, try <a href=
- "http://config.privoxy.org/toggle?set=disable" target=
- "_top">toggling off</a> <span class="APPLICATION">Privoxy</span>,
- and see if the problem persists.
- </p>
- <p>
- If you are using your own custom configuration, please try the
- stock configs to see if the problem is configuration related. If
- you're having problems with a feature that is disabled by
- default, please ask around on the mailing list if others can
- reproduce the problem.
- </p>
- <p>
- If you aren't using the latest Privoxy version, the bug may have
- been found and fixed in the meantime. We would appreciate if you
- could take the time to <a href=
- "http://www.privoxy.org/user-manual/installation.html" target=
- "_top">upgrade to the latest version</a> (or even the latest CVS
- snapshot) and verify that your bug still exists.
- </p>
- <p>
- Please be sure to provide the following information:
- </p>
- <p>
- </p>
- <ul>
- <li>
- <p>
- The exact <span class="APPLICATION">Privoxy</span> version
- you are using (if you got the source from CVS, please also
- provide the source code revisions as shown in <a href=
- "http://config.privoxy.org/show-version" target=
- "_top">http://config.privoxy.org/show-version</a>).
- </p>
- </li>
- <li>
- <p>
- The operating system and versions you run <span class=
- "APPLICATION">Privoxy</span> on, (e.g. <span class=
- "APPLICATION">Windows XP SP2</span>), if you are using a Unix
- flavor, sending the output of <span class="QUOTE">"uname
- -a"</span> should do, in case of GNU/Linux, please also name
- the distribution.
- </p>
- </li>
- <li>
- <p>
- The name, platform, and version of the <span class=
- "APPLICATION">browser</span> you were using (e.g. <span
- class="APPLICATION">Internet Explorer v5.5</span> for Mac).
- </p>
- </li>
- <li>
- <p>
- The URL where the problem occurred, or some way for us to
- duplicate the problem (e.g. <tt class=
- "LITERAL">http://somesite.example.com/?somethingelse=123</tt>).
- </p>
- </li>
- <li>
- <p>
- Whether your version of <span class=
- "APPLICATION">Privoxy</span> is one supplied by the <span
- class="APPLICATION">Privoxy</span> developers via
- SourceForge, or if you got your copy somewhere else.
- </p>
- </li>
- <li>
- <p>
- Whether you are using <span class=
- "APPLICATION">Privoxy</span> in tandem with another proxy
- such as <span class="APPLICATION">Tor</span>. If so, please
- temporary disable the other proxy to see if the symptoms
- change.
- </p>
- </li>
- <li>
- <p>
- Whether you are using a personal firewall product. If so,
- does <span class="APPLICATION">Privoxy</span> work without
- it?
- </p>
- </li>
- <li>
- <p>
- Any other pertinent information to help identify the problem
- such as config or log file excerpts (yes, you should have log
- file entries for each action taken). To get a meaningful
- logfile, please make sure that the <a href=
- "../user-manual/config.html#LOGFILE" target="_top">logfile
- directive</a> is being used and the following <a href=
- "../user-manual/config.html#DEBUG" target="_top">debug
- options</a> are enabled:
- </p>
- <p class="LITERALLAYOUT">
- debug 1 # Log the destination for each request Privoxy let through. See also debug 1024.<br>
-
- debug 2 # show each connection status<br>
-
- debug 4 # show I/O status<br>
-
- debug 8 # show header parsing<br>
-
- debug 128 # debug redirects<br>
-
- debug 256 # debug GIF de-animation<br>
-
- debug 512 # Common Log Format<br>
-
- debug 1024 # Log the destination for requests Privoxy didn't let through, and the reason why.<br>
-
- debug 4096 # Startup banner and warnings.<br>
-
- debug 8192 # Non-fatal errors
- </p>
- If you are having trouble with a filter, please additionally
- enable
- <p class="LITERALLAYOUT">
- debug 64 # debug regular expression filters
- </p>
- If you are using Privoxy 3.0.17 or later and suspect that it
- interprets the request or the response incorrectly, please
- enable
- <p class="LITERALLAYOUT">
- debug 32768 # log all data read from the network
- </p>
- Note that Privoxy log files may contain sensitive information
- so please don't submit any logfiles you didn't read first. You
- can mask sensitive information as long as it's clear that you
- removed something.<br>
- </li>
- </ul>
-
- <p>
- You don't have to tell us your actual name when filing a problem
- report, but if you don't, please use a nickname so we can
- differentiate between your messages and the ones entered by other
- "anonymous" users that may respond to your request if they have
- the same problem or already found a solution. Note that due to
- spam the trackers may not always allow to post without being
- logged into SourceForge. If that's the case, you are still free
- to create a login that isn't directly linked to your name,
- though.
- </p>
- <p>
- Please also check the status of your request a few days after
- submitting it, as we may request additional information. If you
- use a SF id, you should automatically get a mail when someone
- responds to your request. Please don't bother to add an email
- address when using the tracker. If you prefer to communicate
- through email, just use one of the mailing lists directly.
- </p>
- <p>
- The <a href=
- "http://www.privoxy.org/user-manual/appendix.html#ACTIONSANAT"
- target="_top">appendix of the Privoxy User Manual</a> also has
- helpful information on understanding <tt class=
- "LITERAL">actions</tt>, and <tt class="LITERAL">action</tt>
- debugging.
- </p>
- </div>
- </div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="CONTACT-FEATURE">8.3. Request New Features</a>
- </h2>
- <p>
- You are welcome to submit ideas on new features or other proposals
- for improvement through our feature request tracker at <a href=
- "http://sourceforge.net/tracker/?atid=361118&group_id=11118"
- target=
- "_top">http://sourceforge.net/tracker/?atid=361118&group_id=11118</a>.
- </p>
- </div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="MAILING-LISTS">8.4. Mailing Lists</a>
- </h2>
- <p>
- If you prefer to communicate through email, instead of using a web
- interface, feel free to use one of the mailing lists. To discuss
- issues that haven't been completely diagnosed yet, please use the
- Privoxy users list. Technically interested users and people who
- wish to contribute to the project are always welcome on the
- developers list. You can find an overview of all <span class=
- "APPLICATION">Privoxy</span>-related mailing lists, including list
- archives, at: <a href="http://sourceforge.net/mail/?group_id=11118"
- target="_top">http://sourceforge.net/mail/?group_id=11118</a>.
- </p>
+
+ <p>You don't have to tell us your actual name when filing a problem
+ report, but if you don't, please use a nickname so we can
+ differentiate between your messages and the ones entered by other
+ "anonymous" users that may respond to your request if they have the
+ same problem or already found a solution. Note that due to spam the
+ trackers may not always allow to post without being logged into
+ SourceForge. If that's the case, you are still free to create a login
+ that isn't directly linked to your name, though.</p>
+
+ <p>Please also check the status of your request a few days after
+ submitting it, as we may request additional information. If you use a
+ SF id, you should automatically get a mail when someone responds to
+ your request. Please don't bother to add an email address when using
+ the tracker. If you prefer to communicate through email, just use one
+ of the mailing lists directly.</p>
+
+ <p>If you are new to reporting problems, you might be interested in
+ <a href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html"
+ target="_top">How to Report Bugs Effectively</a>.</p>
+
+ <p>If you are new to reporting problems, you might be interested in
+ <a href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html"
+ target="_top">How to Report Bugs Effectively</a>.</p>
+
+ <p>The <a href=
+ "http://www.privoxy.org/user-manual/appendix.html#ACTIONSANAT"
+ target="_top">appendix of the Privoxy User Manual</a> also has
+ helpful information on understanding <tt class=
+ "LITERAL">actions</tt>, and <tt class="LITERAL">action</tt>
+ debugging.</p>
</div>
</div>
- <div class="NAVFOOTER">
- <hr width="100%" class="c1">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
- <tr>
- <td width="33%" align="left" valign="top">
- <a href="webserver-update.html" accesskey="P">Prev</a>
- </td>
- <td width="34%" align="center" valign="top">
- <a href="index.html" accesskey="H">Home</a>
- </td>
- <td width="33%" align="right" valign="top">
- <a href="copyright.html" accesskey="N">Next</a>
- </td>
- </tr>
- <tr>
- <td width="33%" align="left" valign="top">
- Update the Webserver
- </td>
- <td width="34%" align="center" valign="top">
-
- </td>
- <td width="33%" align="right" valign="top">
- Privoxy Copyright, License and History
- </td>
- </tr>
- </table>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="CONTACT-FEATURE" id="CONTACT-FEATURE">8.3.
+ Request New Features</a></h2>
+
+ <p>You are welcome to submit ideas on new features or other proposals
+ for improvement through our feature request tracker at <a href=
+ "http://sourceforge.net/tracker/?atid=361118&group_id=11118"
+ target="_top">http://sourceforge.net/tracker/?atid=361118&group_id=11118</a>.</p>
</div>
- </body>
-</html>
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="MAILING-LISTS" id="MAILING-LISTS">8.4.
+ Mailing Lists</a></h2>
+
+ <p>If you prefer to communicate through email, instead of using a web
+ interface, feel free to use one of the mailing lists. To discuss issues
+ that haven't been completely diagnosed yet, please use the Privoxy
+ users list. Technically interested users and people who wish to
+ contribute to the project are always welcome on the developers list.
+ You can find an overview of all <span class=
+ "APPLICATION">Privoxy</span>-related mailing lists, including list
+ archives, at: <a href="http://sourceforge.net/mail/?group_id=11118"
+ target="_top">http://sourceforge.net/mail/?group_id=11118</a>.</p>
+ </div>
+ </div>
+
+ <div class="NAVFOOTER">
+ <hr class="c1" width="100%">
+
+ <table summary="Footer navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <td width="33%" align="left" valign="top"><a href=
+ "webserver-update.html" accesskey="P">Prev</a></td>
+
+ <td width="34%" align="center" valign="top"><a href="index.html"
+ accesskey="H">Home</a></td>
+
+ <td width="33%" align="right" valign="top"><a href="copyright.html"
+ accesskey="N">Next</a></td>
+ </tr>
+
+ <tr>
+ <td width="33%" align="left" valign="top">Update the Webserver</td>
+
+ <td width="34%" align="center" valign="top"> </td>
+
+ <td width="33%" align="right" valign="top">Privoxy Copyright, License
+ and History</td>
+ </tr>
+ </table>
+ </div>
+</body>
+</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
-Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+"http://www.w3.org/TR/html4/loose.dtd">
+
<html>
- <head>
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>
- Privoxy Copyright, License and History
- </title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
- <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
- <link rel="PREVIOUS" title=
- "Contacting the developers, Bug Reporting and Feature Requests" href=
- "contact.html">
- <link rel="NEXT" title="See also" href="seealso.html">
- <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<style type="text/css">
- body {
+<head>
+ <meta name="generator" content=
+ "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
+
+ <title>Privoxy Copyright, License and History</title>
+ <meta name="GENERATOR" content=
+ "Modular DocBook HTML Stylesheet Version 1.79">
+ <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
+ <link rel="PREVIOUS" title=
+ "Contacting the developers, Bug Reporting and Feature Requests" href=
+ "contact.html">
+ <link rel="NEXT" title="See also" href="seealso.html">
+ <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+ <style type="text/css">
+body {
background-color: #EEEEEE;
color: #000000;
- }
- :link { color: #0000FF }
- :visited { color: #840084 }
- :active { color: #0000FF }
- hr.c1 {text-align: left}
-</style>
- </head>
- <body class="SECT1">
- <div class="NAVHEADER">
- <table summary="Header navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
- <tr>
- <th colspan="3" align="center">
- Privoxy Developer Manual
- </th>
- </tr>
- <tr>
- <td width="10%" align="left" valign="bottom">
- <a href="contact.html" accesskey="P">Prev</a>
- </td>
- <td width="80%" align="center" valign="bottom">
- </td>
- <td width="10%" align="right" valign="bottom">
- <a href="seealso.html" accesskey="N">Next</a>
- </td>
- </tr>
- </table>
- <hr width="100%" class="c1">
- </div>
- <div class="SECT1">
- <h1 class="SECT1">
- <a name="COPYRIGHT">9. Privoxy Copyright, License and History</a>
- </h1>
- <p>
- Copyright © 2001-2011 by Privoxy Developers <code class=
- "EMAIL"><<a href=
- "mailto:ijbswa-developers@lists.sourceforge.net">ijbswa-developers@lists.sourceforge.net</a>></code>
- </p>
- <p>
- Some source code is based on code Copyright © 1997 by Anonymous
- Coders and Junkbusters, Inc. and licensed under the <i class=
- "CITETITLE">GNU General Public License</i>.
- </p>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="AEN1229">9.1. License</a>
- </h2>
- <p>
- <span class="APPLICATION">Privoxy</span> is free software; you can
- redistribute it and/or modify it under the terms of the <i class=
- "CITETITLE">GNU General Public License</i>, version 2, as published
- by the Free Software Foundation.
- </p>
- <p>
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the <a
- href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html"
- target="_top"><i class="CITETITLE">GNU General Public
- License</i></a> for details.
- </p>
- <p>
- You should have received a copy of the <i class="CITETITLE">GNU
- GPL</i> along with this program; if not, write to the
- </p>
- <p class="ADDRESS">
- Free Software<br>
- Foundation, Inc. <span class="STREET">51 Franklin
- Street, Fifth Floor</span><br>
- <span class="CITY">Boston</span>, <span class=
- "STATE">MA</span> <span class="POSTCODE">02110-1301</span><br>
- <span class="COUNTRY">USA</span>
- </p>
- </div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="AEN1245">9.2. History</a>
- </h2>
- <p>
- A long time ago, there was the <a href=
- "http://www.junkbusters.com/ijb.html" target="_top"><span class=
- "APPLICATION">Internet Junkbuster</span></a>, by Anonymous Coders
- and <a href="http://www.junkbusters.com/" target="_top">Junkbusters
- Corporation</a>. This saved many users a lot of pain in the early
- days of web advertising and user tracking.
- </p>
- <p>
- But the web, its protocols and standards, and with it, the
- techniques for forcing ads on users, give up autonomy over their
- browsing, and for tracking them, keeps evolving. Unfortunately, the
- <span class="APPLICATION">Internet Junkbuster</span> did not.
- Version 2.0.2, published in 1998, was (and is) the last official <a
- href="http://www.junkbusters.com/ijbdist.html#release" target=
- "_top">release</a> available from <a href=
- "http://www.junkbusters.com" target="_top">Junkbusters
- Corporation</a>. Fortunately, it had been released under the GNU <a
- href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html"
- target="_top">GPL</a>, which allowed further development by others.
- </p>
- <p>
- So Stefan Waldherr started maintaining an improved version of the
- software, to which eventually a number of people contributed
- patches. It could already replace banners with a transparent image,
- and had a first version of pop-up killing, but it was still very
- closely based on the original, with all its limitations, such as
- the lack of HTTP/1.1 support, flexible per-site configuration, or
- content modification. The last release from this effort was version
- 2.0.2-10, published in 2000.
- </p>
- <p>
- Then, some <a href=
- "http://www.privoxy.org/user-manual/copyright.html#AUTHORS" target=
- "_top">developers</a> picked up the thread, and started turning the
- software inside out, upside down, and then reassembled it, adding
- many <a href=
- "http://www.privoxy.org/user-manual/introduction.html#FEATURES"
- target="_top">new features</a> along the way.
- </p>
- <p>
- The result of this is <span class="APPLICATION">Privoxy</span>,
- whose first stable version, 3.0, was released August, 2002.
- </p>
- </div>
+ }
+ :link { color: #0000FF }
+ :visited { color: #840084 }
+ :active { color: #0000FF }
+ a.c2 {font-style: italic}
+ hr.c1 {text-align: left}
+ </style>
+</head>
+
+<body class="SECT1">
+ <div class="NAVHEADER">
+ <table summary="Header navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <th colspan="3" align="center">Privoxy Developer Manual</th>
+ </tr>
+
+ <tr>
+ <td width="10%" align="left" valign="bottom"><a href="contact.html"
+ accesskey="P">Prev</a></td>
+
+ <td width="80%" align="center" valign="bottom"></td>
+
+ <td width="10%" align="right" valign="bottom"><a href="seealso.html"
+ accesskey="N">Next</a></td>
+ </tr>
+ </table>
+ <hr class="c1" width="100%">
+ </div>
+
+ <div class="SECT1">
+ <h1 class="SECT1"><a name="COPYRIGHT" id="COPYRIGHT">9. Privoxy
+ Copyright, License and History</a></h1>
+
+ <p>Copyright © 2001-2011 by Privoxy Developers <code class=
+ "EMAIL"><<a href=
+ "mailto:ijbswa-developers@lists.sourceforge.net">ijbswa-developers@lists.sourceforge.net</a>></code></p>
+
+ <p>Some source code is based on code Copyright © 1997 by Anonymous
+ Coders and Junkbusters, Inc. and licensed under the <i class=
+ "CITETITLE">GNU General Public License</i>.</p>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="AEN1233" id="AEN1233">9.1. License</a></h2>
+
+ <p><span class="APPLICATION">Privoxy</span> is free software; you can
+ redistribute it and/or modify it under the terms of the <i class=
+ "CITETITLE">GNU General Public License</i>, version 2, as published by
+ the Free Software Foundation.</p>
+
+ <p>This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the <a class=
+ "CITETITLE c2" href=
+ "http://www.gnu.org/licenses/old-licenses/gpl-2.0.html" target=
+ "_top">GNU General Public License</a> for details.</p>
+
+ <p>You should have received a copy of the <i class="CITETITLE">GNU
+ GPL</i> along with this program; if not, write to the</p>
+
+ <p class="ADDRESS"> Free Software<br>
+ Foundation, Inc. <span class="STREET">51 Franklin
+ Street, Fifth Floor</span><br>
+ <span class="CITY">Boston</span>, <span class=
+ "STATE">MA</span> <span class="POSTCODE">02110-1301</span><br>
+ <span class="COUNTRY">USA</span> </p>
</div>
- <div class="NAVFOOTER">
- <hr width="100%" class="c1">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
- <tr>
- <td width="33%" align="left" valign="top">
- <a href="contact.html" accesskey="P">Prev</a>
- </td>
- <td width="34%" align="center" valign="top">
- <a href="index.html" accesskey="H">Home</a>
- </td>
- <td width="33%" align="right" valign="top">
- <a href="seealso.html" accesskey="N">Next</a>
- </td>
- </tr>
- <tr>
- <td width="33%" align="left" valign="top">
- Contacting the developers, Bug Reporting and Feature Requests
- </td>
- <td width="34%" align="center" valign="top">
-
- </td>
- <td width="33%" align="right" valign="top">
- See also
- </td>
- </tr>
- </table>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="AEN1249" id="AEN1249">9.2. History</a></h2>
+
+ <p>A long time ago, there was the <a href=
+ "http://www.junkbusters.com/ijb.html" target="_top"><span class=
+ "APPLICATION">Internet Junkbuster</span></a>, by Anonymous Coders and
+ <a href="http://www.junkbusters.com/" target="_top">Junkbusters
+ Corporation</a>. This saved many users a lot of pain in the early days
+ of web advertising and user tracking.</p>
+
+ <p>But the web, its protocols and standards, and with it, the
+ techniques for forcing ads on users, give up autonomy over their
+ browsing, and for tracking them, keeps evolving. Unfortunately, the
+ <span class="APPLICATION">Internet Junkbuster</span> did not. Version
+ 2.0.2, published in 1998, was (and is) the last official <a href=
+ "http://www.junkbusters.com/ijbdist.html#release" target=
+ "_top">release</a> available from <a href="http://www.junkbusters.com"
+ target="_top">Junkbusters Corporation</a>. Fortunately, it had been
+ released under the GNU <a href=
+ "http://www.gnu.org/licenses/old-licenses/gpl-2.0.html" target=
+ "_top">GPL</a>, which allowed further development by others.</p>
+
+ <p>So Stefan Waldherr started maintaining an improved version of the
+ software, to which eventually a number of people contributed patches.
+ It could already replace banners with a transparent image, and had a
+ first version of pop-up killing, but it was still very closely based on
+ the original, with all its limitations, such as the lack of HTTP/1.1
+ support, flexible per-site configuration, or content modification. The
+ last release from this effort was version 2.0.2-10, published in
+ 2000.</p>
+
+ <p>Then, some <a href=
+ "http://www.privoxy.org/user-manual/copyright.html#AUTHORS" target=
+ "_top">developers</a> picked up the thread, and started turning the
+ software inside out, upside down, and then reassembled it, adding many
+ <a href="http://www.privoxy.org/user-manual/introduction.html#FEATURES"
+ target="_top">new features</a> along the way.</p>
+
+ <p>The result of this is <span class="APPLICATION">Privoxy</span>,
+ whose first stable version, 3.0, was released August, 2002.</p>
</div>
- </body>
-</html>
+ </div>
+ <div class="NAVFOOTER">
+ <hr class="c1" width="100%">
+
+ <table summary="Footer navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <td width="33%" align="left" valign="top"><a href="contact.html"
+ accesskey="P">Prev</a></td>
+
+ <td width="34%" align="center" valign="top"><a href="index.html"
+ accesskey="H">Home</a></td>
+
+ <td width="33%" align="right" valign="top"><a href="seealso.html"
+ accesskey="N">Next</a></td>
+ </tr>
+
+ <tr>
+ <td width="33%" align="left" valign="top">Contacting the developers,
+ Bug Reporting and Feature Requests</td>
+
+ <td width="34%" align="center" valign="top"> </td>
+
+ <td width="33%" align="right" valign="top">See also</td>
+ </tr>
+ </table>
+ </div>
+</body>
+</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
-Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+"http://www.w3.org/TR/html4/loose.dtd">
+
<html>
- <head>
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>
- The CVS Repository
- </title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
- <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
- <link rel="PREVIOUS" title="Introduction" href="introduction.html">
- <link rel="NEXT" title="Documentation Guidelines" href=
- "documentation.html">
- <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<style type="text/css">
- body {
+<head>
+ <meta name="generator" content=
+ "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
+
+ <title>The CVS Repository</title>
+ <meta name="GENERATOR" content=
+ "Modular DocBook HTML Stylesheet Version 1.79">
+ <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
+ <link rel="PREVIOUS" title="Introduction" href="introduction.html">
+ <link rel="NEXT" title="Documentation Guidelines" href=
+ "documentation.html">
+ <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+ <style type="text/css">
+body {
background-color: #EEEEEE;
color: #000000;
- }
- :link { color: #0000FF }
- :visited { color: #840084 }
- :active { color: #0000FF }
- hr.c1 {text-align: left}
-</style>
- </head>
- <body class="SECT1">
- <div class="NAVHEADER">
- <table summary="Header navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
- <tr>
- <th colspan="3" align="center">
- Privoxy Developer Manual
- </th>
- </tr>
- <tr>
- <td width="10%" align="left" valign="bottom">
- <a href="introduction.html" accesskey="P">Prev</a>
- </td>
- <td width="80%" align="center" valign="bottom">
- </td>
- <td width="10%" align="right" valign="bottom">
- <a href="documentation.html" accesskey="N">Next</a>
- </td>
- </tr>
- </table>
- <hr width="100%" class="c1">
+ }
+ :link { color: #0000FF }
+ :visited { color: #840084 }
+ :active { color: #0000FF }
+ span.c2 {font-style: italic}
+ hr.c1 {text-align: left}
+ </style>
+</head>
+
+<body class="SECT1">
+ <div class="NAVHEADER">
+ <table summary="Header navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <th colspan="3" align="center">Privoxy Developer Manual</th>
+ </tr>
+
+ <tr>
+ <td width="10%" align="left" valign="bottom"><a href=
+ "introduction.html" accesskey="P">Prev</a></td>
+
+ <td width="80%" align="center" valign="bottom"></td>
+
+ <td width="10%" align="right" valign="bottom"><a href=
+ "documentation.html" accesskey="N">Next</a></td>
+ </tr>
+ </table>
+ <hr class="c1" width="100%">
+ </div>
+
+ <div class="SECT1">
+ <h1 class="SECT1"><a name="CVS" id="CVS">2. The CVS Repository</a></h1>
+
+ <p>If you become part of the active development team, you will eventually
+ need write access to our holy grail, the CVS repository. One of the team
+ members will need to set this up for you. Please read this chapter
+ completely before accessing via CVS.</p>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="CVSACCESS" id="CVSACCESS">2.1. Access to
+ CVS</a></h2>
+
+ <p>The project's CVS repository is hosted on <a href=
+ "http://sourceforge.net/" target="_top">SourceForge.</a> Please refer
+ to the chapters 6 and 7 in <a href=
+ "http://sourceforge.net/docman/?group_id=1" target="_top">SF's site
+ documentation</a> for the technical access details for your operating
+ system. For historical reasons, the CVS server is called <tt class=
+ "LITERAL">ijbswa.cvs.sourceforge.net</tt>, the repository is called
+ <tt class="LITERAL">ijbswa</tt>, and the source tree module is called
+ <tt class="LITERAL">current</tt>.</p>
</div>
- <div class="SECT1">
- <h1 class="SECT1">
- <a name="CVS">2. The CVS Repository</a>
- </h1>
- <p>
- If you become part of the active development team, you will
- eventually need write access to our holy grail, the CVS repository.
- One of the team members will need to set this up for you. Please read
- this chapter completely before accessing via CVS.
- </p>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="CVSACCESS">2.1. Access to CVS</a>
- </h2>
- <p>
- The project's CVS repository is hosted on <a href=
- "http://sourceforge.net/" target="_top">SourceForge.</a> Please
- refer to the chapters 6 and 7 in <a href=
- "http://sourceforge.net/docman/?group_id=1" target="_top">SF's site
- documentation</a> for the technical access details for your
- operating system. For historical reasons, the CVS server is called
- <tt class="LITERAL">ijbswa.cvs.sourceforge.net</tt>, the repository
- is called <tt class="LITERAL">ijbswa</tt>, and the source tree
- module is called <tt class="LITERAL">current</tt>.
- </p>
- </div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="CVSBRANCHES">2.2. Branches</a>
- </h2>
- <p>
- Within the CVS repository, there are modules and branches. As
- mentioned, the sources are in the <tt class="LITERAL">current</tt>
- <span class="QUOTE">"module"</span>. Other modules are present for
- platform specific issues. There is a webview of the CVS hierarchy
- at <a href="http://ijbswa.cvs.sourceforge.net/ijbswa/" target=
- "_top">http://ijbswa.cvs.sourceforge.net/ijbswa/</a>, which might
- help with visualizing how these pieces fit together.
- </p>
- <p>
- Branches are used to fork a sub-development path from the main
- trunk. Within the <tt class="LITERAL">current</tt> module where the
- sources are, there is always at least one <span class=
- "QUOTE">"branch"</span> from the main trunk devoted to a stable
- release series. The main trunk is where active development takes
- place for the next stable series (e.g. 3.2.x). So just prior to
- each stable series (e.g. 3.0.x), a branch is created just for
- stable series releases (e.g. 3.0.0 -> 3.0.1 -> 3.0.2, etc).
- Once the initial stable release of any stable branch has taken
- place, this branch is <span class="emphasis"><i class=
- "EMPHASIS">only used for bugfixes</i></span>, which have had prior
- testing before being committed to CVS. (See <a href=
- "newrelease.html#VERSIONNUMBERS">Version Numbers</a> below for
- details on versioning.)
- </p>
- <p>
- At one time there were two distinct branches: stable and unstable.
- The more drastic changes were to be in the unstable branch. These
- branches have now been merged to minimize time and effort of
- maintaining two branches.
- </p>
- </div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="CVSCOMMIT">2.3. CVS Commit Guidelines</a>
- </h2>
- <p>
- The source tree is the heart of every software project. Every
- effort must be made to ensure that it is readable, compilable and
- consistent at all times. There are differing guidelines for the
- stable branch and the main development trunk, and we ask anyone
- with CVS access to strictly adhere to the following guidelines:
- </p>
- <p>
- Basic Guidelines, for all branches:
- </p>
- <p>
- </p>
- <ul>
- <li>
- <p>
- Please don't commit even a small change without testing it
- thoroughly first. When we're close to a public release, ask a
- fellow developer to review your changes.
- </p>
- </li>
- <li>
- <p>
- Your commit message should give a concise overview of <span
- class="emphasis"><i class="EMPHASIS">what you
- changed</i></span> (no big details) and <span class=
- "emphasis"><i class="EMPHASIS">why you changed it</i></span>
- Just check previous messages for good examples.
- </p>
- </li>
- <li>
- <p>
- Don't use the same message on multiple files, unless it equally
- applies to all those files.
- </p>
- </li>
- <li>
- <p>
- If your changes span multiple files, and the code won't
- recompile unless all changes are committed (e.g. when changing
- the signature of a function), then commit all files one after
- another, without long delays in between. If necessary, prepare
- the commit messages in advance.
- </p>
- </li>
- <li>
- <p>
- Before changing things on CVS, make sure that your changes are
- in line with the team's general consensus on what should be
- done.
- </p>
- </li>
- <li>
- <p>
- Note that near a major public release, we get more cautious.
- There is always the possibility to submit a patch to the <a
- href=
- "http://sourceforge.net/tracker/?atid=311118&group_id=11118&func=browse"
- target="_top">patch tracker</a> instead.
- </p>
- </li>
- </ul>
- </div>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="CVSBRANCHES" id="CVSBRANCHES">2.2.
+ Branches</a></h2>
+
+ <p>Within the CVS repository, there are modules and branches. As
+ mentioned, the sources are in the <tt class="LITERAL">current</tt>
+ <span class="QUOTE">"module"</span>. Other modules are present for
+ platform specific issues. There is a webview of the CVS hierarchy at
+ <a href="http://ijbswa.cvs.sourceforge.net/ijbswa/" target=
+ "_top">http://ijbswa.cvs.sourceforge.net/ijbswa/</a>, which might help
+ with visualizing how these pieces fit together.</p>
+
+ <p>Branches are used to fork a sub-development path from the main
+ trunk. Within the <tt class="LITERAL">current</tt> module where the
+ sources are, there is always at least one <span class=
+ "QUOTE">"branch"</span> from the main trunk devoted to a stable release
+ series. The main trunk is where active development takes place for the
+ next stable series (e.g. 3.2.x). So just prior to each stable series
+ (e.g. 3.0.x), a branch is created just for stable series releases (e.g.
+ 3.0.0 -> 3.0.1 -> 3.0.2, etc). Once the initial stable release of
+ any stable branch has taken place, this branch is <span class=
+ "emphasis EMPHASIS c2">only used for bugfixes</span>, which have had
+ prior testing before being committed to CVS. (See <a href=
+ "newrelease.html#VERSIONNUMBERS">Version Numbers</a> below for details
+ on versioning.)</p>
+
+ <p>At one time there were two distinct branches: stable and unstable.
+ The more drastic changes were to be in the unstable branch. These
+ branches have now been merged to minimize time and effort of
+ maintaining two branches.</p>
</div>
- <div class="NAVFOOTER">
- <hr width="100%" class="c1">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
- <tr>
- <td width="33%" align="left" valign="top">
- <a href="introduction.html" accesskey="P">Prev</a>
- </td>
- <td width="34%" align="center" valign="top">
- <a href="index.html" accesskey="H">Home</a>
- </td>
- <td width="33%" align="right" valign="top">
- <a href="documentation.html" accesskey="N">Next</a>
- </td>
- </tr>
- <tr>
- <td width="33%" align="left" valign="top">
- Introduction
- </td>
- <td width="34%" align="center" valign="top">
-
- </td>
- <td width="33%" align="right" valign="top">
- Documentation Guidelines
- </td>
- </tr>
- </table>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="CVSCOMMIT" id="CVSCOMMIT">2.3. CVS Commit
+ Guidelines</a></h2>
+
+ <p>The source tree is the heart of every software project. Every effort
+ must be made to ensure that it is readable, compilable and consistent
+ at all times. There are differing guidelines for the stable branch and
+ the main development trunk, and we ask anyone with CVS access to
+ strictly adhere to the following guidelines:</p>
+
+ <p>Basic Guidelines, for all branches:</p>
+
+ <ul>
+ <li>
+ <p>Please don't commit even a small change without testing it
+ thoroughly first. When we're close to a public release, ask a
+ fellow developer to review your changes.</p>
+ </li>
+
+ <li>
+ <p>Your commit message should give a concise overview of
+ <span class="emphasis EMPHASIS c2">what you changed</span> (no big
+ details) and <span class="emphasis EMPHASIS c2">why you changed
+ it</span> Just check previous messages for good examples.</p>
+ </li>
+
+ <li>
+ <p>Don't use the same message on multiple files, unless it equally
+ applies to all those files.</p>
+ </li>
+
+ <li>
+ <p>If your changes span multiple files, and the code won't
+ recompile unless all changes are committed (e.g. when changing the
+ signature of a function), then commit all files one after another,
+ without long delays in between. If necessary, prepare the commit
+ messages in advance.</p>
+ </li>
+
+ <li>
+ <p>Before changing things on CVS, make sure that your changes are
+ in line with the team's general consensus on what should be
+ done.</p>
+ </li>
+
+ <li>
+ <p>Note that near a major public release, we get more cautious.
+ There is always the possibility to submit a patch to the <a href=
+ "http://sourceforge.net/tracker/?atid=311118&group_id=11118&func=browse"
+ target="_top">patch tracker</a> instead.</p>
+ </li>
+ </ul>
</div>
- </body>
-</html>
+ </div>
+ <div class="NAVFOOTER">
+ <hr class="c1" width="100%">
+
+ <table summary="Footer navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <td width="33%" align="left" valign="top"><a href="introduction.html"
+ accesskey="P">Prev</a></td>
+
+ <td width="34%" align="center" valign="top"><a href="index.html"
+ accesskey="H">Home</a></td>
+
+ <td width="33%" align="right" valign="top"><a href=
+ "documentation.html" accesskey="N">Next</a></td>
+ </tr>
+
+ <tr>
+ <td width="33%" align="left" valign="top">Introduction</td>
+
+ <td width="34%" align="center" valign="top"> </td>
+
+ <td width="33%" align="right" valign="top">Documentation
+ Guidelines</td>
+ </tr>
+ </table>
+ </div>
+</body>
+</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
-Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+"http://www.w3.org/TR/html4/loose.dtd">
+
<html>
- <head>
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>
- Documentation Guidelines
- </title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
- <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
- <link rel="PREVIOUS" title="The CVS Repository" href="cvs.html">
- <link rel="NEXT" title="Coding Guidelines" href="coding.html">
- <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<style type="text/css">
- body {
+<head>
+ <meta name="generator" content=
+ "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
+
+ <title>Documentation Guidelines</title>
+ <meta name="GENERATOR" content=
+ "Modular DocBook HTML Stylesheet Version 1.79">
+ <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
+ <link rel="PREVIOUS" title="The CVS Repository" href="cvs.html">
+ <link rel="NEXT" title="Coding Guidelines" href="coding.html">
+ <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+ <style type="text/css">
+body {
background-color: #EEEEEE;
color: #000000;
- }
- :link { color: #0000FF }
- :visited { color: #840084 }
- :active { color: #0000FF }
- hr.c1 {text-align: left}
-</style>
- </head>
- <body class="SECT1">
- <div class="NAVHEADER">
- <table summary="Header navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
- <tr>
- <th colspan="3" align="center">
- Privoxy Developer Manual
- </th>
- </tr>
- <tr>
- <td width="10%" align="left" valign="bottom">
- <a href="cvs.html" accesskey="P">Prev</a>
- </td>
- <td width="80%" align="center" valign="bottom">
- </td>
- <td width="10%" align="right" valign="bottom">
- <a href="coding.html" accesskey="N">Next</a>
- </td>
- </tr>
+ }
+ :link { color: #0000FF }
+ :visited { color: #840084 }
+ :active { color: #0000FF }
+ span.c3 {font-style: italic}
+ a.c2 {font-style: italic}
+ hr.c1 {text-align: left}
+ </style>
+</head>
+
+<body class="SECT1">
+ <div class="NAVHEADER">
+ <table summary="Header navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <th colspan="3" align="center">Privoxy Developer Manual</th>
+ </tr>
+
+ <tr>
+ <td width="10%" align="left" valign="bottom"><a href="cvs.html"
+ accesskey="P">Prev</a></td>
+
+ <td width="80%" align="center" valign="bottom"></td>
+
+ <td width="10%" align="right" valign="bottom"><a href="coding.html"
+ accesskey="N">Next</a></td>
+ </tr>
+ </table>
+ <hr class="c1" width="100%">
+ </div>
+
+ <div class="SECT1">
+ <h1 class="SECT1"><a name="DOCUMENTATION" id="DOCUMENTATION">3.
+ Documentation Guidelines</a></h1>
+
+ <p>All formal documents are maintained in Docbook SGML and located in the
+ <samp class="COMPUTEROUTPUT">doc/source/*</samp> directory. You will need
+ <a href="http://www.docbook.org" target="_top">Docbook</a>, the Docbook
+ DTD's and the Docbook modular stylesheets (or comparable alternatives),
+ and either <span class="APPLICATION">jade</span> or <span class=
+ "APPLICATION">openjade</span> (recommended) installed in order to build
+ docs from source. Currently there is <a class="CITETITLE c2" href=
+ "../user-manual/index.html" target="_top">user-manual</a>, <a class=
+ "CITETITLE c2" href="../faq/index.html" target="_top">FAQ</a>, and, of
+ course this, the <i class="CITETITLE">developer-manual</i> in this
+ format. The <i class="CITETITLE">README</i>, <i class=
+ "CITETITLE">AUTHORS</i>, <i class="CITETITLE">INSTALL</i>, <i class=
+ "CITETITLE">privoxy.1</i> (man page), and <i class="CITETITLE">config</i>
+ files are also now maintained as Docbook SGML. These files, when built,
+ in the top-level source directory are generated files! Also, the
+ <span class="APPLICATION">Privoxy</span> <tt class=
+ "FILENAME">index.html</tt> (and a variation on this file, <tt class=
+ "FILENAME">privoxy-index.html</tt>, meant for inclusion with doc
+ packages), are maintained as SGML as well. <span class=
+ "emphasis EMPHASIS c3">DO NOT edit these directly</span>. Edit the SGML
+ source, or contact someone involved in the documentation.</p>
+
+ <p><tt class="FILENAME">config</tt> requires some special handling. The
+ reason it is maintained this way is so that the extensive comments in the
+ file mirror those in <i class="CITETITLE">user-manual</i>. But the
+ conversion process requires going from SGML to HTML to text to special
+ formatting required for the embedded comments. Some of this does not
+ survive so well. Especially some of the examples that are longer than 80
+ characters. The build process for this file outputs to <tt class=
+ "FILENAME">config.new</tt>, which should be reviewed for errors and
+ mis-formatting. Once satisfied that it is correct, then it should be hand
+ copied to <tt class="FILENAME">config</tt>.</p>
+
+ <p>Other, less formal documents (e.g. <tt class="FILENAME">LICENSE</tt>)
+ are maintained as plain text files in the top-level source directory.</p>
+
+ <p>Packagers are encouraged to include this documentation. For those
+ without the ability to build the docs locally, text versions of each are
+ kept in CVS. HTML versions are also being kept in CVS under <tt class=
+ "FILENAME">doc/webserver/*</tt>. And PDF version are kept in <tt class=
+ "FILENAME">doc/pdf/*</tt>.</p>
+
+ <p>Formal documents are built with the Makefile targets of <samp class=
+ "COMPUTEROUTPUT">make dok</samp>, or alternately <samp class=
+ "COMPUTEROUTPUT">make redhat-dok</samp>. If you have problems, try both.
+ The build process uses the document SGML sources in <samp class=
+ "COMPUTEROUTPUT">doc/source/*/*</samp> to update all text files in
+ <samp class="COMPUTEROUTPUT">doc/text/</samp> and to update all HTML
+ documents in <samp class="COMPUTEROUTPUT">doc/webserver/</samp>.</p>
+
+ <p>Documentation writers should please make sure documents build
+ successfully before committing to CVS, if possible.</p>
+
+ <p>How do you update the webserver (i.e. the pages on privoxy.org)?</p>
+
+ <ol type="1">
+ <li>
+ <p>First, build the docs by running <samp class="COMPUTEROUTPUT">make
+ dok</samp> (or alternately <samp class="COMPUTEROUTPUT">make
+ redhat-dok</samp>). For PDF docs, do <samp class=
+ "COMPUTEROUTPUT">make dok-pdf</samp>.</p>
+ </li>
+
+ <li>
+ <p>Run <samp class="COMPUTEROUTPUT">make webserver</samp> which
+ copies all files from <samp class=
+ "COMPUTEROUTPUT">doc/webserver</samp> to the sourceforge webserver
+ via scp.</p>
+ </li>
+ </ol>
+
+ <p>Finished docs should be occasionally submitted to CVS (<tt class=
+ "FILENAME">doc/webserver/*/*.html</tt>) so that those without the ability
+ to build them locally, have access to them if needed. This is especially
+ important just prior to a new release! Please do this <span class=
+ "emphasis EMPHASIS c3">after</span> the <tt class="LITERAL">$VERSION</tt>
+ and other release specific data in <tt class="FILENAME">configure.in</tt>
+ has been updated (this is done just prior to a new release).</p>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="SGML" id="SGML">3.1. Quickstart to Docbook
+ and SGML</a></h2>
+
+ <p>If you are not familiar with SGML, it is a markup language similar
+ to HTML. Actually, not a mark up language per se, but a language used
+ to define markup languages. In fact, HTML is an SGML application. Both
+ will use <span class="QUOTE">"tags"</span> to format text and other
+ content. SGML tags can be much more varied, and flexible, but do much
+ of the same kinds of things. The tags, or <span class=
+ "QUOTE">"elements"</span>, are definable in SGML. There is no set
+ <span class="QUOTE">"standards"</span>. Since we are using <span class=
+ "APPLICATION">Docbook</span>, our tags are those that are defined by
+ <span class="APPLICATION">Docbook</span>. Much of how the finish
+ document is rendered is determined by the <span class=
+ "QUOTE">"stylesheets"</span>. The stylesheets determine how each tag
+ gets translated to HTML, or other formats.</p>
+
+ <p>Tags in Docbook SGML need to be always <span class=
+ "QUOTE">"closed"</span>. If not, you will likely generate errors.
+ Example: <tt class="LITERAL"><title>My Title</title></tt>.
+ They are also case-insensitive, but we strongly suggest using all lower
+ case. This keeps compatibility with [Docbook] <span class=
+ "APPLICATION">XML</span>.</p>
+
+ <p>Our documents use <span class="QUOTE">"sections"</span> for the most
+ part. Sections will be processed into HTML headers (e.g. <tt class=
+ "LITERAL">h1</tt> for <tt class="LITERAL">sect1</tt>). The <span class=
+ "APPLICATION">Docbook</span> stylesheets will use these to also
+ generate the Table of Contents for each doc. Our TOC's are set to a
+ depth of three. Meaning <tt class="LITERAL">sect1</tt>, <tt class=
+ "LITERAL">sect2</tt>, and <tt class="LITERAL">sect3</tt> will have TOC
+ entries, but <tt class="LITERAL">sect4</tt> will not. Each section
+ requires a <tt class="LITERAL"><title></tt> element, and at least
+ one <tt class="LITERAL"><para></tt>. There is a limit of five
+ section levels in Docbook, but generally three should be sufficient for
+ our purposes.</p>
+
+ <p>Some common elements that you likely will use:</p>
+
+ <table border="0">
+ <tbody>
+ <tr>
+ <td><span class=
+ "emphasis EMPHASIS c3"><para></para></span>,
+ paragraph delimiter. Most text needs to be within paragraph
+ elements (there are some exceptions).</td>
+ </tr>
+
+ <tr>
+ <td><span class=
+ "emphasis EMPHASIS c3"><emphasis></emphasis></span>,
+ the stylesheets make this italics.</td>
+ </tr>
+
+ <tr>
+ <td><span class=
+ "emphasis EMPHASIS c3"><filename></filename></span>,
+ files and directories.</td>
+ </tr>
+
+ <tr>
+ <td><span class=
+ "emphasis EMPHASIS c3"><command></command></span>,
+ command examples.</td>
+ </tr>
+
+ <tr>
+ <td><span class=
+ "emphasis EMPHASIS c3"><literallayout></literallayout></span>,
+ like <tt class="LITERAL"><pre></tt>, more or less.</td>
+ </tr>
+
+ <tr>
+ <td><span class=
+ "emphasis EMPHASIS c3"><itemizedlist></itemizedlist></span>,
+ list with bullets.</td>
+ </tr>
+
+ <tr>
+ <td><span class=
+ "emphasis EMPHASIS c3"><listitem></listitem></span>,
+ member of the above.</td>
+ </tr>
+
+ <tr>
+ <td><span class=
+ "emphasis EMPHASIS c3"><screen></screen></span>,
+ screen output, implies <tt class=
+ "LITERAL"><literallayout></tt>.</td>
+ </tr>
+
+ <tr>
+ <td><span class="emphasis EMPHASIS c3"><ulink
+ url="example.com"></ulink></span>, like HTML <tt class=
+ "LITERAL"><a></tt> tag.</td>
+ </tr>
+
+ <tr>
+ <td><span class=
+ "emphasis EMPHASIS c3"><quote></quote></span>, for,
+ doh, quoting text.</td>
+ </tr>
+ </tbody>
</table>
- <hr width="100%" class="c1">
+
+ <p>Look at any of the existing docs for examples of all these and
+ more.</p>
+
+ <p>You might also find <span class="QUOTE">"<a href=
+ "http://opensource.bureau-cornavin.com/crash-course/index.html" target=
+ "_top">Writing Documentation Using DocBook - A Crash Course</a>"</span>
+ useful.</p>
</div>
- <div class="SECT1">
- <h1 class="SECT1">
- <a name="DOCUMENTATION">3. Documentation Guidelines</a>
- </h1>
- <p>
- All formal documents are maintained in Docbook SGML and located in
- the <samp class="COMPUTEROUTPUT">doc/source/*</samp> directory. You
- will need <a href="http://www.docbook.org" target="_top">Docbook</a>,
- the Docbook DTD's and the Docbook modular stylesheets (or comparable
- alternatives), and either <span class="APPLICATION">jade</span> or
- <span class="APPLICATION">openjade</span> (recommended) installed in
- order to build docs from source. Currently there is <a href=
- "../user-manual/index.html" target="_top"><i class=
- "CITETITLE">user-manual</i></a>, <a href="../faq/index.html" target=
- "_top"><i class="CITETITLE">FAQ</i></a>, and, of course this, the <i
- class="CITETITLE">developer-manual</i> in this format. The <i class=
- "CITETITLE">README</i>, <i class="CITETITLE">AUTHORS</i>, <i class=
- "CITETITLE">INSTALL</i>, <i class="CITETITLE">privoxy.1</i> (man
- page), and <i class="CITETITLE">config</i> files are also now
- maintained as Docbook SGML. These files, when built, in the top-level
- source directory are generated files! Also, the <span class=
- "APPLICATION">Privoxy</span> <tt class="FILENAME">index.html</tt>
- (and a variation on this file, <tt class=
- "FILENAME">privoxy-index.html</tt>, meant for inclusion with doc
- packages), are maintained as SGML as well. <span class="emphasis"><i
- class="EMPHASIS">DO NOT edit these directly</i></span>. Edit the SGML
- source, or contact someone involved in the documentation.
- </p>
- <p>
- <tt class="FILENAME">config</tt> requires some special handling. The
- reason it is maintained this way is so that the extensive comments in
- the file mirror those in <i class="CITETITLE">user-manual</i>. But
- the conversion process requires going from SGML to HTML to text to
- special formatting required for the embedded comments. Some of this
- does not survive so well. Especially some of the examples that are
- longer than 80 characters. The build process for this file outputs to
- <tt class="FILENAME">config.new</tt>, which should be reviewed for
- errors and mis-formatting. Once satisfied that it is correct, then it
- should be hand copied to <tt class="FILENAME">config</tt>.
- </p>
- <p>
- Other, less formal documents (e.g. <tt class="FILENAME">LICENSE</tt>)
- are maintained as plain text files in the top-level source directory.
- </p>
- <p>
- Packagers are encouraged to include this documentation. For those
- without the ability to build the docs locally, text versions of each
- are kept in CVS. HTML versions are also being kept in CVS under <tt
- class="FILENAME">doc/webserver/*</tt>. And PDF version are kept in
- <tt class="FILENAME">doc/pdf/*</tt>.
- </p>
- <p>
- Formal documents are built with the Makefile targets of <samp class=
- "COMPUTEROUTPUT">make dok</samp>, or alternately <samp class=
- "COMPUTEROUTPUT">make redhat-dok</samp>. If you have problems, try
- both. The build process uses the document SGML sources in <samp
- class="COMPUTEROUTPUT">doc/source/*/*</samp> to update all text files
- in <samp class="COMPUTEROUTPUT">doc/text/</samp> and to update all
- HTML documents in <samp class="COMPUTEROUTPUT">doc/webserver/</samp>.
- </p>
- <p>
- Documentation writers should please make sure documents build
- successfully before committing to CVS, if possible.
- </p>
- <p>
- How do you update the webserver (i.e. the pages on privoxy.org)?
- </p>
- <ol type="1">
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="DOCSTYLE" id="DOCSTYLE">3.2. <span class=
+ "APPLICATION">Privoxy</span> Documentation Style</a></h2>
+
+ <p>It will be easier if everyone follows a similar writing style. This
+ just makes it easier to read what someone else has written if it is all
+ done in a similar fashion.</p>
+
+ <p>Here it is:</p>
+
+ <ul>
+ <li>
+ <p>All tags should be lower case.</p>
+ </li>
+
<li>
- <p>
- First, build the docs by running <samp class=
- "COMPUTEROUTPUT">make dok</samp> (or alternately <samp class=
- "COMPUTEROUTPUT">make redhat-dok</samp>). For PDF docs, do <samp
- class="COMPUTEROUTPUT">make dok-pdf</samp>.
- </p>
+ <p>Tags delimiting a <span class=
+ "emphasis EMPHASIS c3">block</span> of text (even small blocks)
+ should be on their own line. Like:</p>
+
+ <p class="LITERALLAYOUT"> <para><br>
+ Some text goes here.<br>
+ </para><br>
+ </p>Tags marking
+ individual words, or few words, should be in-line:
+
+ <p class="LITERALLAYOUT">
+ Just to <emphasis>emphasize</emphasis>, some text goes here.<br>
+
+ </p>
</li>
+
<li>
- <p>
- Run <samp class="COMPUTEROUTPUT">make webserver</samp> which
- copies all files from <samp class=
- "COMPUTEROUTPUT">doc/webserver</samp> to the sourceforge
- webserver via scp.
- </p>
+ <p>Tags should be nested and step indented for block text like:
+ (except in-line tags)</p>
+
+ <p class="LITERALLAYOUT"> <para><br>
+ <itemizedlist><br>
+ <para><br>
+ <listitem><br>
+ Some text goes here in our list example.<br>
+
+ </listitem><br>
+ </para><br>
+ </itemizedlist><br>
+ </para><br>
+ </p>This makes it easier
+ to find the text amongst the tags ;-)
</li>
- </ol>
-
- <p>
- Finished docs should be occasionally submitted to CVS (<tt class=
- "FILENAME">doc/webserver/*/*.html</tt>) so that those without the
- ability to build them locally, have access to them if needed. This is
- especially important just prior to a new release! Please do this
- <span class="emphasis"><i class="EMPHASIS">after</i></span> the <tt
- class="LITERAL">$VERSION</tt> and other release specific data in <tt
- class="FILENAME">configure.in</tt> has been updated (this is done
- just prior to a new release).
- </p>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="SGML">3.1. Quickstart to Docbook and SGML</a>
- </h2>
- <p>
- If you are not familiar with SGML, it is a markup language similar
- to HTML. Actually, not a mark up language per se, but a language
- used to define markup languages. In fact, HTML is an SGML
- application. Both will use <span class="QUOTE">"tags"</span> to
- format text and other content. SGML tags can be much more varied,
- and flexible, but do much of the same kinds of things. The tags, or
- <span class="QUOTE">"elements"</span>, are definable in SGML. There
- is no set <span class="QUOTE">"standards"</span>. Since we are
- using <span class="APPLICATION">Docbook</span>, our tags are those
- that are defined by <span class="APPLICATION">Docbook</span>. Much
- of how the finish document is rendered is determined by the <span
- class="QUOTE">"stylesheets"</span>. The stylesheets determine how
- each tag gets translated to HTML, or other formats.
- </p>
- <p>
- Tags in Docbook SGML need to be always <span class=
- "QUOTE">"closed"</span>. If not, you will likely generate errors.
- Example: <tt class="LITERAL"><title>My
- Title</title></tt>. They are also case-insensitive, but we
- strongly suggest using all lower case. This keeps compatibility
- with [Docbook] <span class="APPLICATION">XML</span>.
- </p>
- <p>
- Our documents use <span class="QUOTE">"sections"</span> for the
- most part. Sections will be processed into HTML headers (e.g. <tt
- class="LITERAL">h1</tt> for <tt class="LITERAL">sect1</tt>). The
- <span class="APPLICATION">Docbook</span> stylesheets will use these
- to also generate the Table of Contents for each doc. Our TOC's are
- set to a depth of three. Meaning <tt class="LITERAL">sect1</tt>,
- <tt class="LITERAL">sect2</tt>, and <tt class="LITERAL">sect3</tt>
- will have TOC entries, but <tt class="LITERAL">sect4</tt> will not.
- Each section requires a <tt class="LITERAL"><title></tt>
- element, and at least one <tt class="LITERAL"><para></tt>.
- There is a limit of five section levels in Docbook, but generally
- three should be sufficient for our purposes.
- </p>
- <p>
- Some common elements that you likely will use:
- </p>
- <p>
- </p>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><para></para></i></span>, paragraph
- delimiter. Most text needs to be within paragraph elements
- (there are some exceptions).
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><emphasis></emphasis></i></span>, the
- stylesheets make this italics.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><filename></filename></i></span>,
- files and directories.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><command></command></i></span>,
- command examples.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><literallayout></literallayout></i></span>,
- like <tt class="LITERAL"><pre></tt>, more or less.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><itemizedlist></itemizedlist></i></span>,
- list with bullets.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><listitem></listitem></i></span>,
- member of the above.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><screen></screen></i></span>, screen
- output, implies <tt class=
- "LITERAL"><literallayout></tt>.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class="EMPHASIS"><ulink
- url="example.com"></ulink></i></span>, like HTML <tt
- class="LITERAL"><a></tt> tag.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS"><quote></quote></i></span>, for, doh,
- quoting text.
- </td>
- </tr>
- </tbody>
- </table>
-
- <p>
- Look at any of the existing docs for examples of all these and
- more.
- </p>
- <p>
- You might also find <span class="QUOTE">"<a href=
- "http://opensource.bureau-cornavin.com/crash-course/index.html"
- target="_top">Writing Documentation Using DocBook - A Crash
- Course</a>"</span> useful.
- </p>
- </div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="DOCSTYLE">3.2. <span class="APPLICATION">Privoxy</span>
- Documentation Style</a>
- </h2>
- <p>
- It will be easier if everyone follows a similar writing style. This
- just makes it easier to read what someone else has written if it is
- all done in a similar fashion.
- </p>
- <p>
- Here it is:
- </p>
- <p>
- </p>
- <ul>
- <li>
- <p>
- All tags should be lower case.
- </p>
- </li>
- <li>
- <p>
- Tags delimiting a <span class="emphasis"><i class=
- "EMPHASIS">block</i></span> of text (even small blocks) should
- be on their own line. Like:
- </p>
- <p class="LITERALLAYOUT">
- <para><br>
- Some text goes here.<br>
- </para><br>
-
- </p>
- Tags marking individual words, or few words, should be in-line:
- <p class="LITERALLAYOUT">
- Just to <emphasis>emphasize</emphasis>, some text goes here.<br>
-
-
- </p>
- </li>
- <li>
- <p>
- Tags should be nested and step indented for block text like:
- (except in-line tags)
- </p>
- <p class="LITERALLAYOUT">
- <para><br>
- <itemizedlist><br>
- <para><br>
- <listitem><br>
- Some text goes here in our list example.<br>
-
- </listitem><br>
- </para><br>
- </itemizedlist><br>
- </para><br>
-
- </p>
- This makes it easier to find the text amongst the tags ;-)<br>
- </li>
- <li>
- <p>
- Use white space to separate logical divisions within a
- document, like between sections. Running everything together
- consistently makes it harder to read and work on.
- </p>
- </li>
- <li>
- <p>
- Do not hesitate to make comments. Comments can either use the
- <comment> element, or the <!-- --> style comment
- familiar from HTML. (Note in Docbook v4.x <comment> is
- replaced by <remark>.)
- </p>
- </li>
- <li>
- <p>
- We have an international audience. Refrain from slang, or
- English idiosyncrasies (too many to list :). Humor also does
- not translate well sometimes.
- </p>
- </li>
- <li>
- <p>
- Try to keep overall line lengths in source files to 80
- characters or less for obvious reasons. This is not always
- possible, with lengthy URLs for instance.
- </p>
- </li>
- <li>
- <p>
- Our documents are available in differing formats. Right now,
- they are just plain text, HTML, and PDF, but others are always
- a future possibility. Be careful with URLs (<ulink>), and
- avoid this mistake:
- </p>
- <p>
- My favorite site is <ulink
- url="http://example.com">here</ulink>.
- </p>
- <p>
- This will render as <span class="QUOTE">"My favorite site is
- here"</span>, which is not real helpful in a text doc. Better
- like this:
- </p>
- <p>
- My favorite site is <ulink
- url="http://example.com">example.com</ulink>.
- </p>
- </li>
- <li>
- <p>
- All documents should be spell checked occasionally. <span
- class="APPLICATION">aspell</span> can check SGML with the <tt
- class="LITERAL">-H</tt> option. (<span class=
- "APPLICATION">ispell</span> I think too.)
- </p>
- </li>
- </ul>
- </div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="AEN217">3.3. Privoxy Custom Entities</a>
- </h2>
- <p>
- <span class="APPLICATION">Privoxy</span> documentation is using a
- number of customized <span class="QUOTE">"entities"</span> to
- facilitate documentation maintenance.
- </p>
- <p>
- We are using a set of <span class="QUOTE">"boilerplate"</span>
- files with generic text, that is used by multiple docs. This way we
- can write something once, and use it repeatedly without having to
- re-write the same content over and over again. If editing such a
- file, keep in mind that it should be <span class="emphasis"><i
- class="EMPHASIS">generic</i></span>. That is the purpose; so it can
- be used in varying contexts without additional modifications.
- </p>
- <p>
- We are also using what <span class="APPLICATION">Docbook</span>
- calls <span class="QUOTE">"internal entities"</span>. These are
- like variables in programming. Well, sort of. For instance, we have
- the <tt class="LITERAL">p-version</tt> entity that contains the
- current <span class="APPLICATION">Privoxy</span> version string.
- You are strongly encouraged to use these where possible. Some of
- these obviously require re-setting with each release (done by the
- Makefile). A sampling of custom entities are listed below. See any
- of the main docs for examples.
- </p>
- <p>
- </p>
- <ul>
- <li>
- <p>
- Re- <span class="QUOTE">"boilerplate"</span> text entities are
- defined like:
- </p>
- <p>
- <tt class="LITERAL"><!entity supported SYSTEM
- "supported.sgml"></tt>
- </p>
- <p>
- In this example, the contents of the file, <tt class=
- "FILENAME">supported.sgml</tt> is available for inclusion
- anywhere in the doc. To make this happen, just reference the
- now defined entity: <tt class="LITERAL">&supported;</tt>
- (starts with an ampersand and ends with a semi-colon), and the
- contents will be dumped into the finished doc at that point.
- </p>
- </li>
- <li>
- <p>
- Commonly used <span class="QUOTE">"internal entities"</span>:
- </p>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS">p-version</i></span>: the <span class=
- "APPLICATION">Privoxy</span> version string, e.g. <span
- class="QUOTE">"3.0.18"</span>.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS">p-status</i></span>: the project status,
- either <span class="QUOTE">"alpha"</span>, <span class=
- "QUOTE">"beta"</span>, or <span class=
- "QUOTE">"stable"</span>.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS">p-not-stable</i></span>: use to conditionally
- include text in <span class="QUOTE">"not stable"</span>
- releases (e.g. <span class="QUOTE">"beta"</span>).
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS">p-stable</i></span>: just the opposite.
- </td>
- </tr>
- <tr>
- <td>
- <span class="emphasis"><i class=
- "EMPHASIS">p-text</i></span>: this doc is only generated
- as text.
- </td>
- </tr>
- </tbody>
- </table>
- </li>
- </ul>
-
- <p>
- There are others in various places that are defined for a specific
- purpose. Read the source!
- </p>
- </div>
+
+ <li>
+ <p>Use white space to separate logical divisions within a document,
+ like between sections. Running everything together consistently
+ makes it harder to read and work on.</p>
+ </li>
+
+ <li>
+ <p>Do not hesitate to make comments. Comments can either use the
+ <comment> element, or the <!-- --> style comment
+ familiar from HTML. (Note in Docbook v4.x <comment> is
+ replaced by <remark>.)</p>
+ </li>
+
+ <li>
+ <p>We have an international audience. Refrain from slang, or
+ English idiosyncrasies (too many to list :). Humor also does not
+ translate well sometimes.</p>
+ </li>
+
+ <li>
+ <p>Try to keep overall line lengths in source files to 80
+ characters or less for obvious reasons. This is not always
+ possible, with lengthy URLs for instance.</p>
+ </li>
+
+ <li>
+ <p>Our documents are available in differing formats. Right now,
+ they are just plain text, HTML, and PDF, but others are always a
+ future possibility. Be careful with URLs (<ulink>), and avoid
+ this mistake:</p>
+
+ <p>My favorite site is <ulink
+ url="http://example.com">here</ulink>.</p>
+
+ <p>This will render as <span class="QUOTE">"My favorite site is
+ here"</span>, which is not real helpful in a text doc. Better like
+ this:</p>
+
+ <p>My favorite site is <ulink
+ url="http://example.com">example.com</ulink>.</p>
+ </li>
+
+ <li>
+ <p>All documents should be spell checked occasionally. <span class=
+ "APPLICATION">aspell</span> can check SGML with the <tt class=
+ "LITERAL">-H</tt> option. (<span class="APPLICATION">ispell</span>
+ I think too.)</p>
+ </li>
+ </ul>
</div>
- <div class="NAVFOOTER">
- <hr width="100%" class="c1">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
- <tr>
- <td width="33%" align="left" valign="top">
- <a href="cvs.html" accesskey="P">Prev</a>
- </td>
- <td width="34%" align="center" valign="top">
- <a href="index.html" accesskey="H">Home</a>
- </td>
- <td width="33%" align="right" valign="top">
- <a href="coding.html" accesskey="N">Next</a>
- </td>
- </tr>
- <tr>
- <td width="33%" align="left" valign="top">
- The CVS Repository
- </td>
- <td width="34%" align="center" valign="top">
-
- </td>
- <td width="33%" align="right" valign="top">
- Coding Guidelines
- </td>
- </tr>
- </table>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="AEN217" id="AEN217">3.3. Privoxy Custom
+ Entities</a></h2>
+
+ <p><span class="APPLICATION">Privoxy</span> documentation is using a
+ number of customized <span class="QUOTE">"entities"</span> to
+ facilitate documentation maintenance.</p>
+
+ <p>We are using a set of <span class="QUOTE">"boilerplate"</span> files
+ with generic text, that is used by multiple docs. This way we can write
+ something once, and use it repeatedly without having to re-write the
+ same content over and over again. If editing such a file, keep in mind
+ that it should be <span class="emphasis EMPHASIS c3">generic</span>.
+ That is the purpose; so it can be used in varying contexts without
+ additional modifications.</p>
+
+ <p>We are also using what <span class="APPLICATION">Docbook</span>
+ calls <span class="QUOTE">"internal entities"</span>. These are like
+ variables in programming. Well, sort of. For instance, we have the
+ <tt class="LITERAL">p-version</tt> entity that contains the current
+ <span class="APPLICATION">Privoxy</span> version string. You are
+ strongly encouraged to use these where possible. Some of these
+ obviously require re-setting with each release (done by the Makefile).
+ A sampling of custom entities are listed below. See any of the main
+ docs for examples.</p>
+
+ <ul>
+ <li>
+ <p>Re- <span class="QUOTE">"boilerplate"</span> text entities are
+ defined like:</p>
+
+ <p><tt class="LITERAL"><!entity supported SYSTEM
+ "supported.sgml"></tt></p>
+
+ <p>In this example, the contents of the file, <tt class=
+ "FILENAME">supported.sgml</tt> is available for inclusion anywhere
+ in the doc. To make this happen, just reference the now defined
+ entity: <tt class="LITERAL">&supported;</tt> (starts with an
+ ampersand and ends with a semi-colon), and the contents will be
+ dumped into the finished doc at that point.</p>
+ </li>
+
+ <li>
+ <p>Commonly used <span class="QUOTE">"internal
+ entities"</span>:</p>
+
+ <table border="0">
+ <tbody>
+ <tr>
+ <td><span class="emphasis EMPHASIS c3">p-version</span>: the
+ <span class="APPLICATION">Privoxy</span> version string, e.g.
+ <span class="QUOTE">"3.0.18"</span>.</td>
+ </tr>
+
+ <tr>
+ <td><span class="emphasis EMPHASIS c3">p-status</span>: the
+ project status, either <span class="QUOTE">"alpha"</span>,
+ <span class="QUOTE">"beta"</span>, or <span class=
+ "QUOTE">"stable"</span>.</td>
+ </tr>
+
+ <tr>
+ <td><span class="emphasis EMPHASIS c3">p-not-stable</span>:
+ use to conditionally include text in <span class="QUOTE">"not
+ stable"</span> releases (e.g. <span class=
+ "QUOTE">"beta"</span>).</td>
+ </tr>
+
+ <tr>
+ <td><span class="emphasis EMPHASIS c3">p-stable</span>: just
+ the opposite.</td>
+ </tr>
+
+ <tr>
+ <td><span class="emphasis EMPHASIS c3">p-text</span>: this
+ doc is only generated as text.</td>
+ </tr>
+ </tbody>
+ </table>
+ </li>
+ </ul>
+
+ <p>There are others in various places that are defined for a specific
+ purpose. Read the source!</p>
</div>
- </body>
-</html>
+ </div>
+
+ <div class="NAVFOOTER">
+ <hr class="c1" width="100%">
+
+ <table summary="Footer navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <td width="33%" align="left" valign="top"><a href="cvs.html"
+ accesskey="P">Prev</a></td>
+ <td width="34%" align="center" valign="top"><a href="index.html"
+ accesskey="H">Home</a></td>
+
+ <td width="33%" align="right" valign="top"><a href="coding.html"
+ accesskey="N">Next</a></td>
+ </tr>
+
+ <tr>
+ <td width="33%" align="left" valign="top">The CVS Repository</td>
+
+ <td width="34%" align="center" valign="top"> </td>
+
+ <td width="33%" align="right" valign="top">Coding Guidelines</td>
+ </tr>
+ </table>
+ </div>
+</body>
+</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
-Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+"http://www.w3.org/TR/html4/loose.dtd">
+
<html>
- <head>
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>
- Privoxy Developer Manual
- </title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
- <link rel="NEXT" title="Introduction" href="introduction.html">
- <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<style type="text/css">
- body {
+<head>
+ <meta name="generator" content=
+ "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
+
+ <title>Privoxy Developer Manual</title>
+ <meta name="GENERATOR" content=
+ "Modular DocBook HTML Stylesheet Version 1.79">
+ <link rel="NEXT" title="Introduction" href="introduction.html">
+ <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+ <style type="text/css">
+body {
background-color: #EEEEEE;
color: #000000;
- }
- :link { color: #0000FF }
- :visited { color: #840084 }
- :active { color: #0000FF }
- hr.c2 {text-align: left}
- dt.c1 {font-weight: bold}
-</style>
- </head>
- <body class="ARTICLE">
- <div class="ARTICLE">
- <div class="TITLEPAGE">
- <h1 class="TITLE">
- <a name="AEN2">Privoxy Developer Manual</a>
- </h1>
- <p class="PUBDATE">
- <sub><a href="copyright.html">Copyright</a> © 2001-2009 by <a
- href="http://www.privoxy.org/" target="_top">Privoxy
- Developers</a></sub><br>
- </p>
- <p class="PUBDATE">
- $Id: index.html,v 1.55 2011/08/17 10:37:48 fabiankeil Exp $<br>
- </p>
- <div>
- <a name="AEN9"></a>
- <p>
- The developer manual provides guidance on coding, testing,
- packaging, documentation and other issues of importance to those
- involved with <span class="APPLICATION">Privoxy</span>
- development. It is mandatory (and helpful!) reading for anyone
- who wants to join the team. Note that it's currently out of date
- and may not be entirely correct. As always, patches are welcome.
- </p>
- <p>
- Please note that this document is constantly evolving. This copy
- represents the state at the release of version 3.0.18. You can
- find the latest version of the this manual at <a href=
- "http://www.privoxy.org/developer-manual/" target=
- "_top">http://www.privoxy.org/developer-manual/</a>. Please see
- <a href="contact.html">the Contact section</a> on how to contact
- the developers.
- </p>
- </div>
- <hr>
- </div>
- <div class="TOC">
- <dl>
- <dt class="c1">
- Table of Contents
- </dt>
- <dt>
- 1. <a href="introduction.html">Introduction</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 1.1. <a href="introduction.html#QUICKSTART">Quickstart to
- Privoxy Development</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 2. <a href="cvs.html">The CVS Repository</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 2.1. <a href="cvs.html#CVSACCESS">Access to CVS</a>
- </dt>
- <dt>
- 2.2. <a href="cvs.html#CVSBRANCHES">Branches</a>
- </dt>
- <dt>
- 2.3. <a href="cvs.html#CVSCOMMIT">CVS Commit Guidelines</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 3. <a href="documentation.html">Documentation Guidelines</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 3.1. <a href="documentation.html#SGML">Quickstart to Docbook
- and SGML</a>
- </dt>
- <dt>
- 3.2. <a href="documentation.html#DOCSTYLE"><span class=
- "APPLICATION">Privoxy</span> Documentation Style</a>
- </dt>
- <dt>
- 3.3. <a href="documentation.html#AEN217">Privoxy Custom
- Entities</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 4. <a href="coding.html">Coding Guidelines</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 4.1. <a href="coding.html#S1">Introduction</a>
- </dt>
- <dt>
- 4.2. <a href="coding.html#S2">Using Comments</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 4.2.1. <a href="coding.html#S3">Comment, Comment,
- Comment</a>
- </dt>
- <dt>
- 4.2.2. <a href="coding.html#S4">Use blocks for
- comments</a>
- </dt>
- <dt>
- 4.2.3. <a href="coding.html#S5">Keep Comments on their
- own line</a>
- </dt>
- <dt>
- 4.2.4. <a href="coding.html#S6">Comment each logical
- step</a>
- </dt>
- <dt>
- 4.2.5. <a href="coding.html#S7">Comment All Functions
- Thoroughly</a>
- </dt>
- <dt>
- 4.2.6. <a href="coding.html#S8">Comment at the end of
- braces if the content is more than one screen length</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 4.3. <a href="coding.html#S9">Naming Conventions</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 4.3.1. <a href="coding.html#S10">Variable Names</a>
- </dt>
- <dt>
- 4.3.2. <a href="coding.html#S11">Function Names</a>
- </dt>
- <dt>
- 4.3.3. <a href="coding.html#S12">Header file
- prototypes</a>
- </dt>
- <dt>
- 4.3.4. <a href="coding.html#S13">Enumerations, and
- #defines</a>
- </dt>
- <dt>
- 4.3.5. <a href="coding.html#S14">Constants</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 4.4. <a href="coding.html#S15">Using Space</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 4.4.1. <a href="coding.html#S16">Put braces on a line by
- themselves.</a>
- </dt>
- <dt>
- 4.4.2. <a href="coding.html#S17">ALL control statements
- should have a block</a>
- </dt>
- <dt>
- 4.4.3. <a href="coding.html#S18">Do not belabor/blow-up
- boolean expressions</a>
- </dt>
- <dt>
- 4.4.4. <a href="coding.html#S19">Use white space freely
- because it is free</a>
- </dt>
- <dt>
- 4.4.5. <a href="coding.html#S20">Don't use white space
- around structure operators</a>
- </dt>
- <dt>
- 4.4.6. <a href="coding.html#S21">Make the last brace of a
- function stand out</a>
- </dt>
- <dt>
- 4.4.7. <a href="coding.html#S22">Use 3 character
- indentions</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 4.5. <a href="coding.html#S23">Initializing</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 4.5.1. <a href="coding.html#S24">Initialize all
- variables</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 4.6. <a href="coding.html#S25">Functions</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 4.6.1. <a href="coding.html#S26">Name functions that
- return a boolean as a question.</a>
- </dt>
- <dt>
- 4.6.2. <a href="coding.html#S27">Always specify a return
- type for a function.</a>
- </dt>
- <dt>
- 4.6.3. <a href="coding.html#S28">Minimize function calls
- when iterating by using variables</a>
- </dt>
- <dt>
- 4.6.4. <a href="coding.html#S29">Pass and Return by Const
- Reference</a>
- </dt>
- <dt>
- 4.6.5. <a href="coding.html#S30">Pass and Return by
- Value</a>
- </dt>
- <dt>
- 4.6.6. <a href="coding.html#S31">Names of include
- files</a>
- </dt>
- <dt>
- 4.6.7. <a href="coding.html#S32">Provide multiple
- inclusion protection</a>
- </dt>
- <dt>
- 4.6.8. <a href="coding.html#S33">Use `extern "C"` when
- appropriate</a>
- </dt>
- <dt>
- 4.6.9. <a href="coding.html#S34">Where Possible, Use
- Forward Struct Declaration Instead of Includes</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 4.7. <a href="coding.html#S35">General Coding Practices</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 4.7.1. <a href="coding.html#S36">Turn on warnings</a>
- </dt>
- <dt>
- 4.7.2. <a href="coding.html#S37">Provide a default case
- for all switch statements</a>
- </dt>
- <dt>
- 4.7.3. <a href="coding.html#S38">Try to avoid falling
- through cases in a switch statement.</a>
- </dt>
- <dt>
- 4.7.4. <a href="coding.html#S39">Use 'long' or 'short'
- Instead of 'int'</a>
- </dt>
- <dt>
- 4.7.5. <a href="coding.html#S40">Don't mix size_t and
- other types</a>
- </dt>
- <dt>
- 4.7.6. <a href="coding.html#S41">Declare each variable
- and struct on its own line.</a>
- </dt>
- <dt>
- 4.7.7. <a href="coding.html#S42">Use malloc/zalloc
- sparingly</a>
- </dt>
- <dt>
- 4.7.8. <a href="coding.html#S43">The Programmer Who Uses
- 'malloc' is Responsible for Ensuring 'free'</a>
- </dt>
- <dt>
- 4.7.9. <a href="coding.html#S44">Add loaders to the
- `file_list' structure and in order</a>
- </dt>
- <dt>
- 4.7.10. <a href="coding.html#S45">"Uncertain" new code
- and/or changes to existing code, use FIXME or XXX</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 4.8. <a href="coding.html#S46">Addendum: Template for files
- and function comment blocks:</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 5. <a href="testing.html">Testing Guidelines</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 5.1. <a href="testing.html#TESTING-PLAN">Testplan for
- releases</a>
- </dt>
- <dt>
- 5.2. <a href="testing.html#TESTING-REPORT">Test reports</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 6. <a href="newrelease.html">Releasing a New Version</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 6.1. <a href="newrelease.html#VERSIONNUMBERS">Version
- numbers</a>
- </dt>
- <dt>
- 6.2. <a href="newrelease.html#BEFORERELEASE">Before the
- Release: Freeze</a>
- </dt>
- <dt>
- 6.3. <a href="newrelease.html#THERELEASE">Building and
- Releasing the Packages</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 6.3.1. <a href="newrelease.html#PACK-GUIDELINES">Note on
- Privoxy Packaging</a>
- </dt>
- <dt>
- 6.3.2. <a href=
- "newrelease.html#NEWRELEASE-TARBALL">Source Tarball</a>
- </dt>
- <dt>
- 6.3.3. <a href="newrelease.html#NEWRELEASE-RPM">SuSE,
- Conectiva or Red Hat RPM</a>
- </dt>
- <dt>
- 6.3.4. <a href="newrelease.html#NEWRELEASE-OS2">OS/2</a>
- </dt>
- <dt>
- 6.3.5. <a href=
- "newrelease.html#NEWRELEASE-SOLARIS">Solaris</a>
- </dt>
- <dt>
- 6.3.6. <a href=
- "newrelease.html#NEWRELEASE-WINDOWS">Windows</a>
- </dt>
- <dt>
- 6.3.7. <a href=
- "newrelease.html#NEWRELEASE-DEBIAN">Debian</a>
- </dt>
- <dt>
- 6.3.8. <a href="newrelease.html#NEWRELEASE-MACOSX">Mac OS
- X</a>
- </dt>
- <dt>
- 6.3.9. <a href=
- "newrelease.html#NEWRELEASE-FREEBSD">FreeBSD</a>
- </dt>
- <dt>
- 6.3.10. <a href="newrelease.html#NEWRELEASE-HPUX">HP-UX
- 11</a>
- </dt>
- <dt>
- 6.3.11. <a href="newrelease.html#NEWRELEASE-AMIGA">Amiga
- OS</a>
- </dt>
- <dt>
- 6.3.12. <a href="newrelease.html#NEWRELEASE-AIX">AIX</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 6.4. <a href="newrelease.html#RELEASING">Uploading and
- Releasing Your Package</a>
- </dt>
- <dt>
- 6.5. <a href="newrelease.html#AFTERRELEASE">After the
- Release</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 7. <a href="webserver-update.html">Update the Webserver</a>
- </dt>
- <dt>
- 8. <a href="contact.html">Contacting the developers, Bug
- Reporting and Feature Requests</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 8.1. <a href="contact.html#CONTACT-SUPPORT">Get Support</a>
- </dt>
- <dt>
- 8.2. <a href="contact.html#REPORTING">Reporting Problems</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 8.2.1. <a href="contact.html#CONTACT-ADS">Reporting Ads
- or Other Configuration Problems</a>
- </dt>
- <dt>
- 8.2.2. <a href="contact.html#CONTACT-BUGS">Reporting
- Bugs</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 8.3. <a href="contact.html#CONTACT-FEATURE">Request New
- Features</a>
- </dt>
- <dt>
- 8.4. <a href="contact.html#MAILING-LISTS">Mailing Lists</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 9. <a href="copyright.html">Privoxy Copyright, License and
- History</a>
- </dt>
- <dd>
- <dl>
- <dt>
- 9.1. <a href="copyright.html#AEN1229">License</a>
- </dt>
- <dt>
- 9.2. <a href="copyright.html#AEN1245">History</a>
- </dt>
- </dl>
- </dd>
- <dt>
- 10. <a href="seealso.html">See also</a>
- </dt>
- </dl>
+ }
+ :link { color: #0000FF }
+ :visited { color: #840084 }
+ :active { color: #0000FF }
+ hr.c2 {text-align: left}
+ dt.c1 {font-weight: bold}
+ </style>
+</head>
+
+<body class="ARTICLE">
+ <div class="ARTICLE">
+ <div class="TITLEPAGE">
+ <h1 class="TITLE"><a name="AEN2" id="AEN2">Privoxy Developer
+ Manual</a></h1>
+
+ <p class="PUBDATE"><sub><a href="copyright.html">Copyright</a> ©
+ 2001-2009 by <a href="http://www.privoxy.org/" target="_top">Privoxy
+ Developers</a></sub><br></p>
+
+ <p class="PUBDATE">$Id: developer-manual.sgml,v 2.36 2011/09/04
+ 11:10:12 fabiankeil Exp $<br></p>
+
+ <div class="ABSTRACT">
+ <a name="AEN9" id="AEN9"></a>
+
+ <p>The developer manual provides guidance on coding, testing,
+ packaging, documentation and other issues of importance to those
+ involved with <span class="APPLICATION">Privoxy</span> development.
+ It is mandatory (and helpful!) reading for anyone who wants to join
+ the team. Note that it's currently out of date and may not be
+ entirely correct. As always, patches are welcome.</p>
+
+ <p>Please note that this document is constantly evolving. This copy
+ represents the state at the release of version 3.0.18. You can find
+ the latest version of the this manual at <a href=
+ "http://www.privoxy.org/developer-manual/" target=
+ "_top">http://www.privoxy.org/developer-manual/</a>. Please see
+ <a href="contact.html">the Contact section</a> on how to contact the
+ developers.</p>
</div>
+ <hr>
</div>
- <div class="NAVFOOTER">
- <hr width="100%" class="c2">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
- <tr>
- <td width="33%" align="left" valign="top">
-
- </td>
- <td width="34%" align="center" valign="top">
-
- </td>
- <td width="33%" align="right" valign="top">
- <a href="introduction.html" accesskey="N">Next</a>
- </td>
- </tr>
- <tr>
- <td width="33%" align="left" valign="top">
-
- </td>
- <td width="34%" align="center" valign="top">
-
- </td>
- <td width="33%" align="right" valign="top">
- Introduction
- </td>
- </tr>
- </table>
+
+ <div class="TOC">
+ <dl>
+ <dt class="c1">Table of Contents</dt>
+
+ <dt>1. <a href="introduction.html">Introduction</a></dt>
+
+ <dd>
+ <dl>
+ <dt>1.1. <a href="introduction.html#QUICKSTART">Quickstart to
+ Privoxy Development</a></dt>
+ </dl>
+ </dd>
+
+ <dt>2. <a href="cvs.html">The CVS Repository</a></dt>
+
+ <dd>
+ <dl>
+ <dt>2.1. <a href="cvs.html#CVSACCESS">Access to CVS</a></dt>
+
+ <dt>2.2. <a href="cvs.html#CVSBRANCHES">Branches</a></dt>
+
+ <dt>2.3. <a href="cvs.html#CVSCOMMIT">CVS Commit
+ Guidelines</a></dt>
+ </dl>
+ </dd>
+
+ <dt>3. <a href="documentation.html">Documentation Guidelines</a></dt>
+
+ <dd>
+ <dl>
+ <dt>3.1. <a href="documentation.html#SGML">Quickstart to Docbook
+ and SGML</a></dt>
+
+ <dt>3.2. <a href="documentation.html#DOCSTYLE"><span class=
+ "APPLICATION">Privoxy</span> Documentation Style</a></dt>
+
+ <dt>3.3. <a href="documentation.html#AEN217">Privoxy Custom
+ Entities</a></dt>
+ </dl>
+ </dd>
+
+ <dt>4. <a href="coding.html">Coding Guidelines</a></dt>
+
+ <dd>
+ <dl>
+ <dt>4.1. <a href="coding.html#S1">Introduction</a></dt>
+
+ <dt>4.2. <a href="coding.html#S2">Using Comments</a></dt>
+
+ <dd>
+ <dl>
+ <dt>4.2.1. <a href="coding.html#S3">Comment, Comment,
+ Comment</a></dt>
+
+ <dt>4.2.2. <a href="coding.html#S4">Use blocks for
+ comments</a></dt>
+
+ <dt>4.2.3. <a href="coding.html#S5">Keep Comments on their
+ own line</a></dt>
+
+ <dt>4.2.4. <a href="coding.html#S6">Comment each logical
+ step</a></dt>
+
+ <dt>4.2.5. <a href="coding.html#S7">Comment All Functions
+ Thoroughly</a></dt>
+
+ <dt>4.2.6. <a href="coding.html#S8">Comment at the end of
+ braces if the content is more than one screen length</a></dt>
+ </dl>
+ </dd>
+
+ <dt>4.3. <a href="coding.html#S9">Naming Conventions</a></dt>
+
+ <dd>
+ <dl>
+ <dt>4.3.1. <a href="coding.html#S10">Variable Names</a></dt>
+
+ <dt>4.3.2. <a href="coding.html#S11">Function Names</a></dt>
+
+ <dt>4.3.3. <a href="coding.html#S12">Header file
+ prototypes</a></dt>
+
+ <dt>4.3.4. <a href="coding.html#S13">Enumerations, and
+ #defines</a></dt>
+
+ <dt>4.3.5. <a href="coding.html#S14">Constants</a></dt>
+ </dl>
+ </dd>
+
+ <dt>4.4. <a href="coding.html#S15">Using Space</a></dt>
+
+ <dd>
+ <dl>
+ <dt>4.4.1. <a href="coding.html#S16">Put braces on a line by
+ themselves.</a></dt>
+
+ <dt>4.4.2. <a href="coding.html#S17">ALL control statements
+ should have a block</a></dt>
+
+ <dt>4.4.3. <a href="coding.html#S18">Do not belabor/blow-up
+ boolean expressions</a></dt>
+
+ <dt>4.4.4. <a href="coding.html#S19">Use white space freely
+ because it is free</a></dt>
+
+ <dt>4.4.5. <a href="coding.html#S20">Don't use white space
+ around structure operators</a></dt>
+
+ <dt>4.4.6. <a href="coding.html#S21">Make the last brace of a
+ function stand out</a></dt>
+
+ <dt>4.4.7. <a href="coding.html#S22">Use 3 character
+ indentions</a></dt>
+ </dl>
+ </dd>
+
+ <dt>4.5. <a href="coding.html#S23">Initializing</a></dt>
+
+ <dd>
+ <dl>
+ <dt>4.5.1. <a href="coding.html#S24">Initialize all
+ variables</a></dt>
+ </dl>
+ </dd>
+
+ <dt>4.6. <a href="coding.html#S25">Functions</a></dt>
+
+ <dd>
+ <dl>
+ <dt>4.6.1. <a href="coding.html#S26">Name functions that
+ return a boolean as a question.</a></dt>
+
+ <dt>4.6.2. <a href="coding.html#S27">Always specify a return
+ type for a function.</a></dt>
+
+ <dt>4.6.3. <a href="coding.html#S28">Minimize function calls
+ when iterating by using variables</a></dt>
+
+ <dt>4.6.4. <a href="coding.html#S29">Pass and Return by Const
+ Reference</a></dt>
+
+ <dt>4.6.5. <a href="coding.html#S30">Pass and Return by
+ Value</a></dt>
+
+ <dt>4.6.6. <a href="coding.html#S31">Names of include
+ files</a></dt>
+
+ <dt>4.6.7. <a href="coding.html#S32">Provide multiple
+ inclusion protection</a></dt>
+
+ <dt>4.6.8. <a href="coding.html#S33">Use `extern "C"` when
+ appropriate</a></dt>
+
+ <dt>4.6.9. <a href="coding.html#S34">Where Possible, Use
+ Forward Struct Declaration Instead of Includes</a></dt>
+ </dl>
+ </dd>
+
+ <dt>4.7. <a href="coding.html#S35">General Coding
+ Practices</a></dt>
+
+ <dd>
+ <dl>
+ <dt>4.7.1. <a href="coding.html#S36">Turn on
+ warnings</a></dt>
+
+ <dt>4.7.2. <a href="coding.html#S37">Provide a default case
+ for all switch statements</a></dt>
+
+ <dt>4.7.3. <a href="coding.html#S38">Try to avoid falling
+ through cases in a switch statement.</a></dt>
+
+ <dt>4.7.4. <a href="coding.html#S39">Use 'long' or 'short'
+ Instead of 'int'</a></dt>
+
+ <dt>4.7.5. <a href="coding.html#S40">Don't mix size_t and
+ other types</a></dt>
+
+ <dt>4.7.6. <a href="coding.html#S41">Declare each variable
+ and struct on its own line.</a></dt>
+
+ <dt>4.7.7. <a href="coding.html#S42">Use malloc/zalloc
+ sparingly</a></dt>
+
+ <dt>4.7.8. <a href="coding.html#S43">The Programmer Who Uses
+ 'malloc' is Responsible for Ensuring 'free'</a></dt>
+
+ <dt>4.7.9. <a href="coding.html#S44">Add loaders to the
+ `file_list' structure and in order</a></dt>
+
+ <dt>4.7.10. <a href="coding.html#S45">"Uncertain" new code
+ and/or changes to existing code, use FIXME or XXX</a></dt>
+ </dl>
+ </dd>
+
+ <dt>4.8. <a href="coding.html#S46">Addendum: Template for files
+ and function comment blocks:</a></dt>
+ </dl>
+ </dd>
+
+ <dt>5. <a href="testing.html">Testing Guidelines</a></dt>
+
+ <dd>
+ <dl>
+ <dt>5.1. <a href="testing.html#TESTING-PLAN">Testplan for
+ releases</a></dt>
+
+ <dt>5.2. <a href="testing.html#TESTING-REPORT">Test
+ reports</a></dt>
+ </dl>
+ </dd>
+
+ <dt>6. <a href="newrelease.html">Releasing a New Version</a></dt>
+
+ <dd>
+ <dl>
+ <dt>6.1. <a href="newrelease.html#VERSIONNUMBERS">Version
+ numbers</a></dt>
+
+ <dt>6.2. <a href="newrelease.html#BEFORERELEASE">Before the
+ Release: Freeze</a></dt>
+
+ <dt>6.3. <a href="newrelease.html#THERELEASE">Building and
+ Releasing the Packages</a></dt>
+
+ <dd>
+ <dl>
+ <dt>6.3.1. <a href="newrelease.html#PACK-GUIDELINES">Note on
+ Privoxy Packaging</a></dt>
+
+ <dt>6.3.2. <a href=
+ "newrelease.html#NEWRELEASE-TARBALL">Source Tarball</a></dt>
+
+ <dt>6.3.3. <a href="newrelease.html#NEWRELEASE-RPM">SuSE,
+ Conectiva or Red Hat RPM</a></dt>
+
+ <dt>6.3.4. <a href=
+ "newrelease.html#NEWRELEASE-OS2">OS/2</a></dt>
+
+ <dt>6.3.5. <a href=
+ "newrelease.html#NEWRELEASE-SOLARIS">Solaris</a></dt>
+
+ <dt>6.3.6. <a href=
+ "newrelease.html#NEWRELEASE-WINDOWS">Windows</a></dt>
+
+ <dt>6.3.7. <a href=
+ "newrelease.html#NEWRELEASE-DEBIAN">Debian</a></dt>
+
+ <dt>6.3.8. <a href="newrelease.html#NEWRELEASE-MACOSX">Mac OS
+ X</a></dt>
+
+ <dt>6.3.9. <a href=
+ "newrelease.html#NEWRELEASE-FREEBSD">FreeBSD</a></dt>
+
+ <dt>6.3.10. <a href="newrelease.html#NEWRELEASE-HPUX">HP-UX
+ 11</a></dt>
+
+ <dt>6.3.11. <a href="newrelease.html#NEWRELEASE-AMIGA">Amiga
+ OS</a></dt>
+
+ <dt>6.3.12. <a href=
+ "newrelease.html#NEWRELEASE-AIX">AIX</a></dt>
+ </dl>
+ </dd>
+
+ <dt>6.4. <a href="newrelease.html#RELEASING">Uploading and
+ Releasing Your Package</a></dt>
+
+ <dt>6.5. <a href="newrelease.html#AFTERRELEASE">After the
+ Release</a></dt>
+ </dl>
+ </dd>
+
+ <dt>7. <a href="webserver-update.html">Update the Webserver</a></dt>
+
+ <dt>8. <a href="contact.html">Contacting the developers, Bug
+ Reporting and Feature Requests</a></dt>
+
+ <dd>
+ <dl>
+ <dt>8.1. <a href="contact.html#CONTACT-SUPPORT">Get
+ Support</a></dt>
+
+ <dt>8.2. <a href="contact.html#REPORTING">Reporting
+ Problems</a></dt>
+
+ <dd>
+ <dl>
+ <dt>8.2.1. <a href="contact.html#CONTACT-ADS">Reporting Ads
+ or Other Configuration Problems</a></dt>
+
+ <dt>8.2.2. <a href="contact.html#CONTACT-BUGS">Reporting
+ Bugs</a></dt>
+ </dl>
+ </dd>
+
+ <dt>8.3. <a href="contact.html#CONTACT-FEATURE">Request New
+ Features</a></dt>
+
+ <dt>8.4. <a href="contact.html#MAILING-LISTS">Mailing
+ Lists</a></dt>
+ </dl>
+ </dd>
+
+ <dt>9. <a href="copyright.html">Privoxy Copyright, License and
+ History</a></dt>
+
+ <dd>
+ <dl>
+ <dt>9.1. <a href="copyright.html#AEN1233">License</a></dt>
+
+ <dt>9.2. <a href="copyright.html#AEN1249">History</a></dt>
+ </dl>
+ </dd>
+
+ <dt>10. <a href="seealso.html">See also</a></dt>
+ </dl>
</div>
- </body>
-</html>
+ </div>
+
+ <div class="NAVFOOTER">
+ <hr class="c2" width="100%">
+ <table summary="Footer navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <td width="33%" align="left" valign="top"> </td>
+
+ <td width="34%" align="center" valign="top"> </td>
+
+ <td width="33%" align="right" valign="top"><a href=
+ "introduction.html" accesskey="N">Next</a></td>
+ </tr>
+
+ <tr>
+ <td width="33%" align="left" valign="top"> </td>
+
+ <td width="34%" align="center" valign="top"> </td>
+
+ <td width="33%" align="right" valign="top">Introduction</td>
+ </tr>
+ </table>
+ </div>
+</body>
+</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
-Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+"http://www.w3.org/TR/html4/loose.dtd">
+
<html>
- <head>
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>
- Introduction
- </title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
- <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
- <link rel="PREVIOUS" title="Privoxy Developer Manual" href="index.html">
- <link rel="NEXT" title="The CVS Repository" href="cvs.html">
- <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<style type="text/css">
- body {
+<head>
+ <meta name="generator" content=
+ "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
+
+ <title>Introduction</title>
+ <meta name="GENERATOR" content=
+ "Modular DocBook HTML Stylesheet Version 1.79">
+ <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
+ <link rel="PREVIOUS" title="Privoxy Developer Manual" href="index.html">
+ <link rel="NEXT" title="The CVS Repository" href="cvs.html">
+ <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+ <style type="text/css">
+body {
background-color: #EEEEEE;
color: #000000;
- }
- :link { color: #0000FF }
- :visited { color: #840084 }
- :active { color: #0000FF }
- hr.c1 {text-align: left}
-</style>
- </head>
- <body class="SECT1">
- <div class="NAVHEADER">
- <table summary="Header navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
- <tr>
- <th colspan="3" align="center">
- Privoxy Developer Manual
- </th>
- </tr>
- <tr>
- <td width="10%" align="left" valign="bottom">
- <a href="index.html" accesskey="P">Prev</a>
- </td>
- <td width="80%" align="center" valign="bottom">
- </td>
- <td width="10%" align="right" valign="bottom">
- <a href="cvs.html" accesskey="N">Next</a>
- </td>
- </tr>
- </table>
- <hr width="100%" class="c1">
- </div>
- <div class="SECT1">
- <h1 class="SECT1">
- <a name="INTRODUCTION">1. Introduction</a>
- </h1>
- <p>
- <span class="APPLICATION">Privoxy</span>, as an heir to <span class=
- "APPLICATION">Junkbuster</span>, is a Free Software project and the
- code is licensed under the GNU General Public License version 2. As
- such, <span class="APPLICATION">Privoxy</span> development is
- potentially open to anyone who has the time, knowledge, and desire to
- contribute in any capacity. Our goals are simply to continue the
- mission, to improve <span class="APPLICATION">Privoxy</span>, and to
- make it available to as wide an audience as possible.
- </p>
- <p>
- One does not have to be a programmer to contribute. Packaging,
- testing, documenting and porting, are all important jobs as well.
- </p>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="QUICKSTART">1.1. Quickstart to Privoxy Development</a>
- </h2>
- <p>
- The first step is to join the <a href=
- "mailto:ijbswa-developers@lists.sourceforge.net" target=
- "_top">developer's mailing list</a>. You can submit your ideas, or
- even better patches. Patches are best submitted to the Sourceforge
- tracker set up for this purpose, but can be sent to the list for
- review too.
- </p>
- <p>
- You will also need to have a cvs package installed, which will
- entail having ssh installed as well (which seems to be a
- requirement of SourceForge), in order to access the cvs repository.
- Having the GNU build tools is also going to be important
- (particularly, autoconf and gmake).
- </p>
- <p>
- For the time being (read, this section is under construction), you
- can also refer to the extensive comments in the source code. In
- fact, reading the code is recommended in any case.
- </p>
- </div>
- </div>
- <div class="NAVFOOTER">
- <hr width="100%" class="c1">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
- <tr>
- <td width="33%" align="left" valign="top">
- <a href="index.html" accesskey="P">Prev</a>
- </td>
- <td width="34%" align="center" valign="top">
- <a href="index.html" accesskey="H">Home</a>
- </td>
- <td width="33%" align="right" valign="top">
- <a href="cvs.html" accesskey="N">Next</a>
- </td>
- </tr>
- <tr>
- <td width="33%" align="left" valign="top">
- Privoxy Developer Manual
- </td>
- <td width="34%" align="center" valign="top">
-
- </td>
- <td width="33%" align="right" valign="top">
- The CVS Repository
- </td>
- </tr>
- </table>
+ }
+ :link { color: #0000FF }
+ :visited { color: #840084 }
+ :active { color: #0000FF }
+ hr.c1 {text-align: left}
+ </style>
+</head>
+
+<body class="SECT1">
+ <div class="NAVHEADER">
+ <table summary="Header navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <th colspan="3" align="center">Privoxy Developer Manual</th>
+ </tr>
+
+ <tr>
+ <td width="10%" align="left" valign="bottom"><a href="index.html"
+ accesskey="P">Prev</a></td>
+
+ <td width="80%" align="center" valign="bottom"></td>
+
+ <td width="10%" align="right" valign="bottom"><a href="cvs.html"
+ accesskey="N">Next</a></td>
+ </tr>
+ </table>
+ <hr class="c1" width="100%">
+ </div>
+
+ <div class="SECT1">
+ <h1 class="SECT1"><a name="INTRODUCTION" id="INTRODUCTION">1.
+ Introduction</a></h1>
+
+ <p><span class="APPLICATION">Privoxy</span>, as an heir to <span class=
+ "APPLICATION">Junkbuster</span>, is a Free Software project and the code
+ is licensed under the GNU General Public License version 2. As such,
+ <span class="APPLICATION">Privoxy</span> development is potentially open
+ to anyone who has the time, knowledge, and desire to contribute in any
+ capacity. Our goals are simply to continue the mission, to improve
+ <span class="APPLICATION">Privoxy</span>, and to make it available to as
+ wide an audience as possible.</p>
+
+ <p>One does not have to be a programmer to contribute. Packaging,
+ testing, documenting and porting, are all important jobs as well.</p>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="QUICKSTART" id="QUICKSTART">1.1. Quickstart
+ to Privoxy Development</a></h2>
+
+ <p>The first step is to join the <a href=
+ "mailto:ijbswa-developers@lists.sourceforge.net" target=
+ "_top">developer's mailing list</a>. You can submit your ideas, or even
+ better patches. Patches are best submitted to the Sourceforge tracker
+ set up for this purpose, but can be sent to the list for review
+ too.</p>
+
+ <p>You will also need to have a cvs package installed, which will
+ entail having ssh installed as well (which seems to be a requirement of
+ SourceForge), in order to access the cvs repository. Having the GNU
+ build tools is also going to be important (particularly, autoconf and
+ gmake).</p>
+
+ <p>For the time being (read, this section is under construction), you
+ can also refer to the extensive comments in the source code. In fact,
+ reading the code is recommended in any case.</p>
</div>
- </body>
-</html>
+ </div>
+
+ <div class="NAVFOOTER">
+ <hr class="c1" width="100%">
+
+ <table summary="Footer navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <td width="33%" align="left" valign="top"><a href="index.html"
+ accesskey="P">Prev</a></td>
+ <td width="34%" align="center" valign="top"><a href="index.html"
+ accesskey="H">Home</a></td>
+
+ <td width="33%" align="right" valign="top"><a href="cvs.html"
+ accesskey="N">Next</a></td>
+ </tr>
+
+ <tr>
+ <td width="33%" align="left" valign="top">Privoxy Developer
+ Manual</td>
+
+ <td width="34%" align="center" valign="top"> </td>
+
+ <td width="33%" align="right" valign="top">The CVS Repository</td>
+ </tr>
+ </table>
+ </div>
+</body>
+</html>
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01
-Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+"http://www.w3.org/TR/html4/loose.dtd">
+
<html>
- <head>
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>
- Releasing a New Version
- </title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
- <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
- <link rel="PREVIOUS" title="Testing Guidelines" href="testing.html">
- <link rel="NEXT" title="Update the Webserver" href=
- "webserver-update.html">
- <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<style type="text/css">
- body {
+<head>
+ <meta name="generator" content=
+ "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
+
+ <title>Releasing a New Version</title>
+ <meta name="GENERATOR" content=
+ "Modular DocBook HTML Stylesheet Version 1.79">
+ <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
+ <link rel="PREVIOUS" title="Testing Guidelines" href="testing.html">
+ <link rel="NEXT" title="Update the Webserver" href="webserver-update.html">
+ <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+ <style type="text/css">
+body {
background-color: #EEEEEE;
color: #000000;
- }
- :link { color: #0000FF }
- :visited { color: #840084 }
- :active { color: #0000FF }
- hr.c1 {text-align: left}
-</style>
- </head>
- <body class="SECT1">
- <div class="NAVHEADER">
- <table summary="Header navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
- <tr>
- <th colspan="3" align="center">
- Privoxy Developer Manual
- </th>
- </tr>
+ }
+ :link { color: #0000FF }
+ :visited { color: #840084 }
+ :active { color: #0000FF }
+ tt.c5 {font-style: italic}
+ td.c4 {font-weight: bold}
+ table.c3 {background-color: #E0E0E0}
+ span.c2 {font-style: italic}
+ hr.c1 {text-align: left}
+ </style>
+</head>
+
+<body class="SECT1">
+ <div class="NAVHEADER">
+ <table summary="Header navigation table" width="100%" border="0"
+ cellpadding="0" cellspacing="0">
+ <tr>
+ <th colspan="3" align="center">Privoxy Developer Manual</th>
+ </tr>
+
+ <tr>
+ <td width="10%" align="left" valign="bottom"><a href="testing.html"
+ accesskey="P">Prev</a></td>
+
+ <td width="80%" align="center" valign="bottom"></td>
+
+ <td width="10%" align="right" valign="bottom"><a href=
+ "webserver-update.html" accesskey="N">Next</a></td>
+ </tr>
+ </table>
+ <hr class="c1" width="100%">
+ </div>
+
+ <div class="SECT1">
+ <h1 class="SECT1"><a name="NEWRELEASE" id="NEWRELEASE">6. Releasing a New
+ Version</a></h1>
+
+ <p>When we release versions of <span class="APPLICATION">Privoxy</span>,
+ our work leaves our cozy secret lab and has to work in the cold
+ RealWorld[tm]. Once it is released, there is no way to call it back, so
+ it is very important that great care is taken to ensure that everything
+ runs fine, and not to introduce problems in the very last minute.</p>
+
+ <p>So when releasing a new version, please adhere exactly to the
+ procedure outlined in this chapter.</p>
+
+ <p>The following programs are required to follow this process: <tt class=
+ "FILENAME">ncftpput</tt> (ncftp), <tt class="FILENAME">scp, ssh</tt>
+ (ssh), <tt class="FILENAME">gmake</tt> (GNU's version of make), autoconf,
+ cvs.</p>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="VERSIONNUMBERS" id="VERSIONNUMBERS">6.1.
+ Version numbers</a></h2>
+
+ <p>First you need to determine which version number the release will
+ have. <span class="APPLICATION">Privoxy</span> version numbers consist
+ of three numbers, separated by dots, like in X.Y.Z (e.g. 3.0.0),
+ where:</p>
+
+ <ul>
+ <li>
+ <p>X, the version major, is rarely ever changed. It is increased by
+ one if turning a development branch into stable substantially
+ changes the functionality, user interface or configuration syntax.
+ Majors 1 and 2 were <span class="APPLICATION">Junkbuster</span>,
+ and 3 will be the first stable <span class=
+ "APPLICATION">Privoxy</span> release.</p>
+ </li>
+
+ <li>
+ <p>Y, the version minor, represents the branch within the major
+ version. At any point in time, there are two branches being
+ maintained: The stable branch, with an even minor, say, 2N, in
+ which no functionality is being added and only bug-fixes are made,
+ and 2N+1, the development branch, in which the further development
+ of <span class="APPLICATION">Privoxy</span> takes place. This
+ enables us to turn the code upside down and inside out, while at
+ the same time providing and maintaining a stable version. The minor
+ is reset to zero (and one) when the major is incremented. When a
+ development branch has matured to the point where it can be turned
+ into stable, the old stable branch 2N is given up (i.e. no longer
+ maintained), the former development branch 2N+1 becomes the new
+ stable branch 2N+2, and a new development branch 2N+3 is
+ opened.</p>
+ </li>
+
+ <li>
+ <p>Z, the point or sub version, represents a release of the
+ software within a branch. It is therefore incremented immediately
+ before each code freeze. In development branches, only the even
+ point versions correspond to actual releases, while the odd ones
+ denote the evolving state of the sources on CVS in between. It
+ follows that Z is odd on CVS in development branches most of the
+ time. There, it gets increased to an even number immediately before
+ a code freeze, and is increased to an odd number again immediately
+ thereafter. This ensures that builds from CVS snapshots are easily
+ distinguished from released versions. The point version is reset to
+ zero when the minor changes.</p>
+
+ <p>Stable branches work a little differently, since there should be
+ little to no development happening in such branches. Remember, only
+ bugfixes, which presumably should have had some testing before
+ being committed. Stable branches will then have their version
+ reported as <tt class="LITERAL">0.0.0</tt>, during that period
+ between releases when changes are being added. This is to denote
+ that this code is <span class="emphasis EMPHASIS c2">not for
+ release</span>. Then as the release nears, the version is bumped
+ according: e.g. <tt class="LITERAL">3.0.1 -> 0.0.0 ->
+ 3.0.2</tt>.</p>
+ </li>
+ </ul>
+
+ <p>In summary, the main CVS trunk is the development branch where new
+ features are being worked on for the next stable series. This should
+ almost always be where the most activity takes place. There is always
+ at least one stable branch from the trunk, e.g now it is <tt class=
+ "LITERAL">3.0</tt>, which is only used to release stable versions. Once
+ the initial *.0 release of the stable branch has been done, then as a
+ rule, only bugfixes that have had prior testing should be committed to
+ the stable branch. Once there are enough bugfixes to justify a new
+ release, the version of this branch is again incremented Example: 3.0.0
+ -> 3.0.1 -> 3.0.2, etc are all stable releases from within the
+ stable branch. 3.1.x is currently the main trunk, and where work on
+ 3.2.x is taking place. If any questions, please post to the devel list
+ <span class="emphasis EMPHASIS c2">before</span> committing to a stable
+ branch!</p>
+
+ <p>Developers should remember too that if they commit a bugfix to the
+ stable branch, this will more than likely require a separate submission
+ to the main trunk, since these are separate development trees within
+ CVS. If you are working on both, then this would require at least two
+ separate check outs (i.e main trunk, <span class=
+ "emphasis EMPHASIS c2">and</span> the stable release branch, which is
+ <tt class="LITERAL">v_3_0_branch</tt> at the moment).</p>
+ </div>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="BEFORERELEASE" id="BEFORERELEASE">6.2.
+ Before the Release: Freeze</a></h2>
+
+ <p>The following <span class="emphasis EMPHASIS c2">must be done by one
+ of the developers</span> prior to each new release.</p>
+
+ <ul>
+ <li>
+ <p>Make sure that everybody who has worked on the code in the last
+ couple of days has had a chance to yell <span class=
+ "QUOTE">"no!"</span> in case they have pending changes/fixes in
+ their pipelines. Announce the freeze so that nobody will interfere
+ with last minute changes.</p>
+ </li>
+
+ <li>
+ <p>Increment the version number (point from odd to even in
+ development branches!) in <tt class="FILENAME">configure.in</tt>.
+ (RPM spec files will need to be incremented as well.)</p>
+ </li>
+
+ <li>
+ <p>If <tt class="FILENAME">default.action</tt> has changed since
+ last release (i.e. software release or standalone actions file
+ release), bump up its version info to A.B in this line:</p>
+
+ <table class="c3" border="0" width="90%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+ {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>Then change the version info in doc/webserver/actions/index.php,
+ line: '$required_actions_file_version = "A.B";'</p>
+ </li>
+
+ <li>
+ <p>All documentation should be rebuild after the version bump.
+ Finished docs should be then be committed to CVS (for those without
+ the ability to build these). Some docs may require rather obscure
+ processing tools. <tt class="FILENAME">config</tt>, the man page
+ (and the html version of the man page), and the PDF docs fall in
+ this category. REAMDE, the man page, AUTHORS, and config should all
+ also be committed to CVS for other packagers. The formal docs
+ should be uploaded to the webserver. See the Section "Updating the
+ webserver" in this manual for details.</p>
+ </li>
+
+ <li>
+ <p>The <i class="CITETITLE">User Manual</i> is also used for
+ context sensitive help for the CGI editor. This is version
+ sensitive, so that the user will get appropriate help for his/her
+ release. So with each release a fresh version should be uploaded to
+ the webserver (this is in addition to the main <i class=
+ "CITETITLE">User Manual</i> link from the main page since we need
+ to keep manuals for various versions available). The CGI pages will
+ link to something like <tt class=
+ "LITERAL">http://privoxy.org/$(VERSION)/user-manual/</tt>. This
+ will need to be updated for each new release. There is no Makefile
+ target for this at this time!!! It needs to be done manually.</p>
+ </li>
+
+ <li>
+ <p>All developers should look at the <tt class=
+ "FILENAME">ChangeLog</tt> and make sure noteworthy changes are
+ referenced.</p>
+ </li>
+
+ <li>
+ <p><span class="emphasis EMPHASIS c2">Commit all files that were
+ changed in the above steps!</span></p>
+ </li>
+
+ <li>
+ <p>Tag all files in CVS with the version number with <span class=
+ "QUOTE">"<b class="COMMAND">cvs tag v_X_Y_Z</b>"</span>. Don't use
+ vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.</p>
+ </li>
+
+ <li>
+ <p>If the release was in a development branch, increase the point
+ version from even to odd (X.Y.(Z+1)) again in <tt class=
+ "FILENAME">configure.in</tt> and commit your change.</p>
+ </li>
+
+ <li>
+ <p>On the webserver, copy the user manual to a new top-level
+ directory called <tt class="FILENAME">X.Y.Z</tt>. This ensures that
+ help links from the CGI pages, which have the version as a prefix,
+ will go into the right version of the manual. If this is a
+ development branch release, also symlink <tt class=
+ "FILENAME">X.Y.(Z-1)</tt> to <tt class="FILENAME">X.Y.Z</tt> and
+ <tt class="FILENAME">X.Y.(Z+1)</tt> to <tt class="FILENAME">.</tt>
+ (i.e. dot).</p>
+ </li>
+ </ul>
+ </div>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="THERELEASE" id="THERELEASE">6.3. Building
+ and Releasing the Packages</a></h2>
+
+ <p>Now the individual packages can be built and released. Note that for
+ GPL reasons the first package to be released is always the source
+ tarball.</p>
+
+ <p>For <span class="emphasis EMPHASIS c2">all</span> types of packages,
+ including the source tarball, <span class="emphasis EMPHASIS c2">you
+ must make sure that you build from clean sources by exporting the right
+ version from CVS into an empty directory</span> (just press return when
+ asked for a password):</p>
+
+ <table class="c3" border="0" width="100%">
<tr>
- <td width="10%" align="left" valign="bottom">
- <a href="testing.html" accesskey="P">Prev</a>
- </td>
- <td width="80%" align="center" valign="bottom">
- </td>
- <td width="10%" align="right" valign="bottom">
- <a href="webserver-update.html" accesskey="N">Next</a>
+ <td>
+ <pre class="PROGRAMLISTING">
+ mkdir dist # delete or choose different name if it already exists
+ cd dist
+ cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+</pre>
</td>
</tr>
</table>
- <hr width="100%" class="c1">
- </div>
- <div class="SECT1">
- <h1 class="SECT1">
- <a name="NEWRELEASE">6. Releasing a New Version</a>
- </h1>
- <p>
- When we release versions of <span class="APPLICATION">Privoxy</span>,
- our work leaves our cozy secret lab and has to work in the cold
- RealWorld[tm]. Once it is released, there is no way to call it back,
- so it is very important that great care is taken to ensure that
- everything runs fine, and not to introduce problems in the very last
- minute.
- </p>
- <p>
- So when releasing a new version, please adhere exactly to the
- procedure outlined in this chapter.
- </p>
- <p>
- The following programs are required to follow this process: <tt
- class="FILENAME">ncftpput</tt> (ncftp), <tt class="FILENAME">scp,
- ssh</tt> (ssh), <tt class="FILENAME">gmake</tt> (GNU's version of
- make), autoconf, cvs.
- </p>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="VERSIONNUMBERS">6.1. Version numbers</a>
- </h2>
- <p>
- First you need to determine which version number the release will
- have. <span class="APPLICATION">Privoxy</span> version numbers
- consist of three numbers, separated by dots, like in X.Y.Z (e.g.
- 3.0.0), where:
- </p>
- <ul>
- <li>
- <p>
- X, the version major, is rarely ever changed. It is increased
- by one if turning a development branch into stable
- substantially changes the functionality, user interface or
- configuration syntax. Majors 1 and 2 were <span class=
- "APPLICATION">Junkbuster</span>, and 3 will be the first stable
- <span class="APPLICATION">Privoxy</span> release.
- </p>
- </li>
- <li>
- <p>
- Y, the version minor, represents the branch within the major
- version. At any point in time, there are two branches being
- maintained: The stable branch, with an even minor, say, 2N, in
- which no functionality is being added and only bug-fixes are
- made, and 2N+1, the development branch, in which the further
- development of <span class="APPLICATION">Privoxy</span> takes
- place. This enables us to turn the code upside down and inside
- out, while at the same time providing and maintaining a stable
- version. The minor is reset to zero (and one) when the major is
- incremented. When a development branch has matured to the point
- where it can be turned into stable, the old stable branch 2N is
- given up (i.e. no longer maintained), the former development
- branch 2N+1 becomes the new stable branch 2N+2, and a new
- development branch 2N+3 is opened.
- </p>
- </li>
- <li>
- <p>
- Z, the point or sub version, represents a release of the
- software within a branch. It is therefore incremented
- immediately before each code freeze. In development branches,
- only the even point versions correspond to actual releases,
- while the odd ones denote the evolving state of the sources on
- CVS in between. It follows that Z is odd on CVS in development
- branches most of the time. There, it gets increased to an even
- number immediately before a code freeze, and is increased to an
- odd number again immediately thereafter. This ensures that
- builds from CVS snapshots are easily distinguished from
- released versions. The point version is reset to zero when the
- minor changes.
- </p>
- <p>
- Stable branches work a little differently, since there should
- be little to no development happening in such branches.
- Remember, only bugfixes, which presumably should have had some
- testing before being committed. Stable branches will then have
- their version reported as <tt class="LITERAL">0.0.0</tt>,
- during that period between releases when changes are being
- added. This is to denote that this code is <span class=
- "emphasis"><i class="EMPHASIS">not for release</i></span>. Then
- as the release nears, the version is bumped according: e.g. <tt
- class="LITERAL">3.0.1 -> 0.0.0 -> 3.0.2</tt>.
- </p>
- </li>
- </ul>
- <p>
- In summary, the main CVS trunk is the development branch where new
- features are being worked on for the next stable series. This
- should almost always be where the most activity takes place. There
- is always at least one stable branch from the trunk, e.g now it is
- <tt class="LITERAL">3.0</tt>, which is only used to release stable
- versions. Once the initial *.0 release of the stable branch has
- been done, then as a rule, only bugfixes that have had prior
- testing should be committed to the stable branch. Once there are
- enough bugfixes to justify a new release, the version of this
- branch is again incremented Example: 3.0.0 -> 3.0.1 -> 3.0.2,
- etc are all stable releases from within the stable branch. 3.1.x is
- currently the main trunk, and where work on 3.2.x is taking place.
- If any questions, please post to the devel list <span class=
- "emphasis"><i class="EMPHASIS">before</i></span> committing to a
- stable branch!
- </p>
- <p>
- Developers should remember too that if they commit a bugfix to the
- stable branch, this will more than likely require a separate
- submission to the main trunk, since these are separate development
- trees within CVS. If you are working on both, then this would
- require at least two separate check outs (i.e main trunk, <span
- class="emphasis"><i class="EMPHASIS">and</i></span> the stable
- release branch, which is <tt class="LITERAL">v_3_0_branch</tt> at
- the moment).
- </p>
+ <p><span class="emphasis EMPHASIS c2">Do NOT change</span> a single
+ bit, including, but not limited to version information after export
+ from CVS. This is to make sure that all release packages, and with
+ them, all future bug reports, are based on exactly the same code.</p>
+
+ <div class="WARNING">
+ <table class="WARNING" border="1" width="100%">
+ <tr>
+ <td class="c4" align="center">Warning</td>
+ </tr>
+
+ <tr>
+ <td align="left">
+ <p>Every significant release of Privoxy has included at least
+ one package that either had incorrect versions of files,
+ missing files, or incidental leftovers from a previous build
+ process that gave unknown numbers of users headaches to try to
+ figure out what was wrong. PLEASE, make sure you are using
+ pristene sources, and are following the prescribed process!</p>
+ </td>
+ </tr>
+ </table>
</div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="BEFORERELEASE">6.2. Before the Release: Freeze</a>
- </h2>
- <p>
- The following <span class="emphasis"><i class="EMPHASIS">must be
- done by one of the developers</i></span> prior to each new release.
- </p>
- <p>
- </p>
+
+ <p>Please find additional instructions for the source tarball and the
+ individual platform dependent binary packages below. And details on the
+ Sourceforge release process below that.</p>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="PACK-GUIDELINES" id=
+ "PACK-GUIDELINES">6.3.1. Note on Privoxy Packaging</a></h3>
+
+ <p>Please keep these general guidelines in mind when putting together
+ your package. These apply to <span class=
+ "emphasis EMPHASIS c2">all</span> platforms!</p>
+
<ul>
<li>
- <p>
- Make sure that everybody who has worked on the code in the last
- couple of days has had a chance to yell <span class=
- "QUOTE">"no!"</span> in case they have pending changes/fixes in
- their pipelines. Announce the freeze so that nobody will
- interfere with last minute changes.
- </p>
- </li>
- <li>
- <p>
- Increment the version number (point from odd to even in
- development branches!) in <tt class=
- "FILENAME">configure.in</tt>. (RPM spec files will need to be
- incremented as well.)
- </p>
+ <p><span class="APPLICATION">Privoxy</span> <span class=
+ "emphasis EMPHASIS c2">requires</span> write access to: all
+ <tt class="FILENAME">*.action</tt> files, all logfiles, and the
+ <tt class="FILENAME">trust</tt> file. You will need to determine
+ the best way to do this for your platform.</p>
</li>
+
<li>
- <p>
- If <tt class="FILENAME">default.action</tt> has changed since
- last release (i.e. software release or standalone actions file
- release), bump up its version info to A.B in this line:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="90%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
- {+add-header{X-Actions-File-Version: A.B} -filter -no-popups}
-</pre>
- </td>
- </tr>
+ <p>Please include up to date documentation. At a bare
+ minimum:</p>
+
+ <table border="0">
+ <tbody>
+ <tr>
+ <td><tt class="FILENAME">LICENSE</tt> (top-level
+ directory)</td>
+ </tr>
+ </tbody>
</table>
- <p>
- Then change the version info in
- doc/webserver/actions/index.php, line:
- '$required_actions_file_version = "A.B";'
- </p>
- </li>
- <li>
- <p>
- All documentation should be rebuild after the version bump.
- Finished docs should be then be committed to CVS (for those
- without the ability to build these). Some docs may require
- rather obscure processing tools. <tt class=
- "FILENAME">config</tt>, the man page (and the html version of
- the man page), and the PDF docs fall in this category. REAMDE,
- the man page, AUTHORS, and config should all also be committed
- to CVS for other packagers. The formal docs should be uploaded
- to the webserver. See the Section "Updating the webserver" in
- this manual for details.
- </p>
- </li>
- <li>
- <p>
- The <i class="CITETITLE">User Manual</i> is also used for
- context sensitive help for the CGI editor. This is version
- sensitive, so that the user will get appropriate help for
- his/her release. So with each release a fresh version should be
- uploaded to the webserver (this is in addition to the main <i
- class="CITETITLE">User Manual</i> link from the main page since
- we need to keep manuals for various versions available). The
- CGI pages will link to something like <tt class=
- "LITERAL">http://privoxy.org/$(VERSION)/user-manual/</tt>. This
- will need to be updated for each new release. There is no
- Makefile target for this at this time!!! It needs to be done
- manually.
- </p>
- </li>
- <li>
- <p>
- All developers should look at the <tt class=
- "FILENAME">ChangeLog</tt> and make sure noteworthy changes are
- referenced.
- </p>
+ <table border="0">
+ <tbody>
+ <tr>
+ <td><tt class="FILENAME">README</tt> (top-level
+ directory)</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <table border="0">
+ <tbody>
+ <tr>
+ <td><tt class="FILENAME">AUTHORS</tt> (top-level
+ directory)</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <table border="0">
+ <tbody>
+ <tr>
+ <td><tt class="FILENAME">man page</tt> (top-level
+ directory, Unix-like platforms only)</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <table border="0">
+ <tbody>
+ <tr>
+ <td><tt class="FILENAME">The User Manual</tt>
+ (doc/webserver/user-manual/)</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <table border="0">
+ <tbody>
+ <tr>
+ <td><tt class="FILENAME">FAQ</tt> (doc/webserver/faq/)</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <p>Also suggested: <tt class="FILENAME">Developer Manual</tt>
+ (doc/webserver/developer-manual) and <tt class=
+ "FILENAME">ChangeLog</tt> (top-level directory). <tt class=
+ "FILENAME">FAQ</tt> and the manuals are HTML docs. There are also
+ text versions in <tt class="FILENAME">doc/text/</tt> which could
+ conceivably also be included.</p>
+
+ <p>The documentation has been designed such that the manuals are
+ linked to each other from parallel directories, and should be
+ packaged that way. <tt class="FILENAME">privoxy-index.html</tt>
+ can also be included and can serve as a focal point for docs and
+ other links of interest (and possibly renamed to <tt class=
+ "FILENAME">index.html</tt>). This should be one level up from the
+ manuals. There is a link also on this page to an HTMLized version
+ of the man page. To avoid 404 for this, it is in CVS as
+ <tt class="FILENAME">doc/webserver/man-page/privoxy-man-page.html</tt>,
+ and should be included along with the manuals. There is also a
+ css stylesheets that can be included for better presentation:
+ <tt class="FILENAME">p_doc.css</tt>. This should be in the same
+ directory with <tt class="FILENAME">privoxy-index.html</tt>,
+ (i.e. one level up from the manual directories).</p>
</li>
+
<li>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Commit all files
- that were changed in the above steps!</i></span>
- </p>
+ <p><tt class="FILENAME">user.action</tt> and <tt class=
+ "FILENAME">user.filter</tt> are designed for local preferences.
+ Make sure these do not get overwritten! <tt class=
+ "FILENAME">config</tt> should not be overwritten either. This has
+ especially important configuration data in it. <tt class=
+ "FILENAME">trust</tt> should be left in tact as well.</p>
</li>
+
<li>
- <p>
- Tag all files in CVS with the version number with <span class=
- "QUOTE">"<b class="COMMAND">cvs tag v_X_Y_Z</b>"</span>. Don't
- use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc.
- </p>
+ <p>Other configuration files (<tt class=
+ "FILENAME">default.action</tt> and <tt class=
+ "FILENAME">default.filter</tt>) should be installed as the new
+ defaults, but all previously installed configuration files should
+ be preserved as backups. This is just good manners :-) These
+ files are likely to change between releases and contain important
+ new features and bug fixes.</p>
</li>
+
<li>
- <p>
- If the release was in a development branch, increase the point
- version from even to odd (X.Y.(Z+1)) again in <tt class=
- "FILENAME">configure.in</tt> and commit your change.
- </p>
+ <p>Please check platform specific notes in this doc, if you
+ haven't done <span class="QUOTE">"Privoxy"</span> packaging
+ before for other platform specific issues. Conversely, please add
+ any notes that you know are important for your platform (or
+ contact one of the doc maintainers to do this if you can't).</p>
</li>
+
<li>
- <p>
- On the webserver, copy the user manual to a new top-level
- directory called <tt class="FILENAME">X.Y.Z</tt>. This ensures
- that help links from the CGI pages, which have the version as a
- prefix, will go into the right version of the manual. If this
- is a development branch release, also symlink <tt class=
- "FILENAME">X.Y.(Z-1)</tt> to <tt class="FILENAME">X.Y.Z</tt>
- and <tt class="FILENAME">X.Y.(Z+1)</tt> to <tt class=
- "FILENAME">.</tt> (i.e. dot).
- </p>
+ <p>Packagers should do a <span class="QUOTE">"clean"</span>
+ install of their package after building it. So any previous
+ installs should be removed first to ensure the integrity of the
+ newly built package. Then run the package for a while to make
+ sure there are no obvious problems, before uploading.</p>
</li>
</ul>
</div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="THERELEASE">6.3. Building and Releasing the Packages</a>
- </h2>
- <p>
- Now the individual packages can be built and released. Note that
- for GPL reasons the first package to be released is always the
- source tarball.
- </p>
- <p>
- For <span class="emphasis"><i class="EMPHASIS">all</i></span> types
- of packages, including the source tarball, <span class=
- "emphasis"><i class="EMPHASIS">you must make sure that you build
- from clean sources by exporting the right version from CVS into an
- empty directory</i></span> (just press return when asked for a
- password):
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="NEWRELEASE-TARBALL" id=
+ "NEWRELEASE-TARBALL">6.3.2. Source Tarball</a></h3>
+
+ <p>First, <span class="emphasis EMPHASIS c2">make sure that you have
+ freshly exported the right version into an empty directory</span>.
+ (See "Building and releasing packages" above). Then run:</p>
+
+ <table class="c3" border="0" width="100%">
<tr>
<td>
-<pre class="PROGRAMLISTING">
- mkdir dist # delete or choose different name if it already exists
- cd dist
- cvs -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa login
- cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current
+ <pre class="PROGRAMLISTING">
+ cd current
+ autoheader && autoconf && ./configure
</pre>
</td>
</tr>
</table>
- <p>
- <span class="emphasis"><i class="EMPHASIS">Do NOT change</i></span>
- a single bit, including, but not limited to version information
- after export from CVS. This is to make sure that all release
- packages, and with them, all future bug reports, are based on
- exactly the same code.
- </p>
- <div class="WARNING">
- <table class="WARNING" border="1" width="100%">
- <tr>
- <td align="CENTER">
- <b>Warning</b>
- </td>
- </tr>
- <tr>
- <td align="LEFT">
- <p>
- Every significant release of Privoxy has included at least
- one package that either had incorrect versions of files,
- missing files, or incidental leftovers from a previous
- build process that gave unknown numbers of users headaches
- to try to figure out what was wrong. PLEASE, make sure you
- are using pristene sources, and are following the
- prescribed process!
- </p>
- </td>
- </tr>
- </table>
- </div>
- <p>
- Please find additional instructions for the source tarball and the
- individual platform dependent binary packages below. And details on
- the Sourceforge release process below that.
- </p>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="PACK-GUIDELINES">6.3.1. Note on Privoxy Packaging</a>
- </h3>
- <p>
- Please keep these general guidelines in mind when putting
- together your package. These apply to <span class="emphasis"><i
- class="EMPHASIS">all</i></span> platforms!
- </p>
- <p>
- </p>
- <ul>
- <li>
- <p>
- <span class="APPLICATION">Privoxy</span> <span class=
- "emphasis"><i class="EMPHASIS">requires</i></span> write
- access to: all <tt class="FILENAME">*.action</tt> files, all
- logfiles, and the <tt class="FILENAME">trust</tt> file. You
- will need to determine the best way to do this for your
- platform.
- </p>
- </li>
- <li>
- <p>
- Please include up to date documentation. At a bare minimum:
- </p>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <tt class="FILENAME">LICENSE</tt> (top-level directory)
- </td>
- </tr>
- </tbody>
- </table>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <tt class="FILENAME">README</tt> (top-level directory)
- </td>
- </tr>
- </tbody>
- </table>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <tt class="FILENAME">AUTHORS</tt> (top-level directory)
- </td>
- </tr>
- </tbody>
- </table>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <tt class="FILENAME">man page</tt> (top-level
- directory, Unix-like platforms only)
- </td>
- </tr>
- </tbody>
- </table>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <tt class="FILENAME">The User Manual</tt>
- (doc/webserver/user-manual/)
- </td>
- </tr>
- </tbody>
- </table>
- <table border="0">
- <tbody>
- <tr>
- <td>
- <tt class="FILENAME">FAQ</tt> (doc/webserver/faq/)
- </td>
- </tr>
- </tbody>
- </table>
- <p>
- Also suggested: <tt class="FILENAME">Developer Manual</tt>
- (doc/webserver/developer-manual) and <tt class=
- "FILENAME">ChangeLog</tt> (top-level directory). <tt class=
- "FILENAME">FAQ</tt> and the manuals are HTML docs. There are
- also text versions in <tt class="FILENAME">doc/text/</tt>
- which could conceivably also be included.
- </p>
- <p>
- The documentation has been designed such that the manuals are
- linked to each other from parallel directories, and should be
- packaged that way. <tt class=
- "FILENAME">privoxy-index.html</tt> can also be included and
- can serve as a focal point for docs and other links of
- interest (and possibly renamed to <tt class=
- "FILENAME">index.html</tt>). This should be one level up from
- the manuals. There is a link also on this page to an HTMLized
- version of the man page. To avoid 404 for this, it is in CVS
- as <tt class=
- "FILENAME">doc/webserver/man-page/privoxy-man-page.html</tt>,
- and should be included along with the manuals. There is also
- a css stylesheets that can be included for better
- presentation: <tt class="FILENAME">p_doc.css</tt>. This
- should be in the same directory with <tt class=
- "FILENAME">privoxy-index.html</tt>, (i.e. one level up from
- the manual directories).
- </p>
- </li>
- <li>
- <p>
- <tt class="FILENAME">user.action</tt> and <tt class=
- "FILENAME">user.filter</tt> are designed for local
- preferences. Make sure these do not get overwritten! <tt
- class="FILENAME">config</tt> should not be overwritten
- either. This has especially important configuration data in
- it. <tt class="FILENAME">trust</tt> should be left in tact as
- well.
- </p>
- </li>
- <li>
- <p>
- Other configuration files (<tt class=
- "FILENAME">default.action</tt> and <tt class=
- "FILENAME">default.filter</tt>) should be installed as the
- new defaults, but all previously installed configuration
- files should be preserved as backups. This is just good
- manners :-) These files are likely to change between releases
- and contain important new features and bug fixes.
- </p>
- </li>
- <li>
- <p>
- Please check platform specific notes in this doc, if you
- haven't done <span class="QUOTE">"Privoxy"</span> packaging
- before for other platform specific issues. Conversely, please
- add any notes that you know are important for your platform
- (or contact one of the doc maintainers to do this if you
- can't).
- </p>
- </li>
- <li>
- <p>
- Packagers should do a <span class="QUOTE">"clean"</span>
- install of their package after building it. So any previous
projects / privoxy.git / commitdiff