-<!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>
- <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">
- </head>
- <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
- "#840084" alink="#0000FF">
- <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 align="LEFT" width="100%">
+<head>
+ <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">
+</head>
+
+<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
+"#840084" alink="#0000FF">
+ <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 align="left" 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 fellow Privoxy developers 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"><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 fellow Privoxy
+ developers 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">
/* 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"><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">
/*********************************************************************
* 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"><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" id="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">
/*********************************************************************
* 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"><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" id="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" 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"><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">
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"><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">
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"><i class="EMPHASIS">Instead
+ of:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><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">
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"><i class="EMPHASIS">Instead
+ of:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><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">
(.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"><i class="EMPHASIS">Instead
+ of:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><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">
(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"><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">
#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"><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">
#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"><i class="EMPHASIS">Instead
+ of:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><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">
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"><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">
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"><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">
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"><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" id="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">
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"><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" id="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">
int first_value = 0;
int some_value = 0;
int another_value = 0;
int this_variable = 0;
</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"><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">
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"><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" id="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">
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"><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" id="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">
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"><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">
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"><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>
- <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"><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">
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"><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" id="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">
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"><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">
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"><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" id="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" id="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" id="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">
#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"><i class=
+ "EMPHASIS">Exception:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><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" id="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">
#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"><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">
#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"><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">
/*********************************************************************
* 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"><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>
+ </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"><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="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 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"><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">
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="S40">4.7.4. 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.5. 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"><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" id="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="S40" id="S40">4.7.4. 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" id="S41">4.7.5. 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">
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.6. 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"><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" id="S42">4.7.6. 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">
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.7. 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">
-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.8. 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.9. "Uncertain" new code and/or changes to
- existing code, use 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>
- /* XXX: this code has a logic error on platform XYZ, * attempting
- to fix */ #ifdef PLATFORM ...changed code here... #endif
- </p>
- <p>
- or:
- </p>
- <p>
- /* XXX: I think the original author really meant this... */
- ...changed code here...
- </p>
- <p>
- or:
- </p>
- <p>
- /* XXX: 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>
</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>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S43" id="S43">4.7.7. 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">
+ <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" id="S44">4.7.8. 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" id="S45">4.7.9. "Uncertain" new code
+ and/or changes to existing code, use 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>/* XXX: this code has a logic error on platform XYZ, * attempting
+ to fix */ #ifdef PLATFORM ...changed code here... #endif</p>
+
+ <p>or:</p>
+
+ <p>/* XXX: I think the original author really meant this... */
+ ...changed code here...</p>
+
+ <p>or:</p>
+
+ <p>/* XXX: 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>
+ </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"><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[] = "$I<!-- Break CVS Substitution -->d$";
/*********************************************************************
*
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"><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">
#ifndef _FILENAME_H
#define _FILENAME_H
#define FILENAME_H_VERSION "$I<!-- Break CVS Substitution -->d$"
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"><i class="EMPHASIS">Example for function
+ comments:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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 align="LEFT" 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>
+
+ <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>
- </body>
-</html>
+ </div>
+
+ <div class="NAVFOOTER">
+ <hr align="left" 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>
- <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">
- </head>
- <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
- "#840084" alink="#0000FF">
- <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 align="LEFT" width="100%">
+<head>
+ <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">
+</head>
+
+<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
+"#840084" alink="#0000FF">
+ <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 align="left" 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=
+ "https://sourceforge.net/" target="_top">SourceForge.</a> 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=
- "https://sourceforge.net/" target="_top">SourceForge.</a> 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/viewvc/ijbswa/"
- target="_top">http://ijbswa.cvs.sourceforge.net/viewvc/ijbswa/</a>,
- which might help with visualizing how these pieces fit together.
- </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. We expect 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=
- "https://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/viewvc/ijbswa/" target=
+ "_top">http://ijbswa.cvs.sourceforge.net/viewvc/ijbswa/</a>, which
+ might help with visualizing how these pieces fit together.</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 align="LEFT" 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 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. We expect 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"><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=
+ "https://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 align="left" 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>
- <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">
- </head>
- <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
- "#840084" alink="#0000FF">
- <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>
+<head>
+ <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">
+</head>
+
+<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
+"#840084" alink="#0000FF">
+ <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 align="left" 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 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>.</p>
+
+ <p>Formal documents are built with the Makefile targets of <samp class=
+ "COMPUTEROUTPUT">make dok</samp>. 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>.</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"><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" 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"><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>
- <hr align="LEFT" width="100%">
+
+ <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>.
- </p>
- <p>
- Formal documents are built with the Makefile targets of <samp class=
- "COMPUTEROUTPUT">make dok</samp>. 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>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 ;-)
+ </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>
- First, build the docs by running <samp class=
- "COMPUTEROUTPUT">make dok</samp>.
- </p>
+ <p>Our documents are available in differing formats. Right now,
+ they are just plain text and/or HTML, 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>
- 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>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>
- </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 and/or HTML, 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="AEN207">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.26"</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>
+ </ul>
</div>
- <div class="NAVFOOTER">
- <hr align="LEFT" 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 class="SECT2">
+ <h2 class="SECT2"><a name="AEN207" id="AEN207">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>
+
+ <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.26"</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>
- </body>
-</html>
+ </div>
+
+ <div class="NAVFOOTER">
+ <hr align="left" 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>
- <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">
- </head>
- <body class="ARTICLE" bgcolor="#EEEEEE" text="#000000" link="#0000FF"
- vlink="#840084" alink="#0000FF">
- <div class="ARTICLE">
- <div class="TITLEPAGE">
- <h1 class="TITLE">
- <a name="AEN2">Privoxy Developer Manual</a>
- </h1>
- <p class="PUBDATE">
- <sub><a href="https://www.privoxy.org/user-manual/copyright.html"
- target="_top">Copyright</a> © 2001-2016 by <a href=
- "https://www.privoxy.org/" target="_top">Privoxy
- Developers</a></sub><br>
- </p>
- <p class="PUBDATE">
- $Id: developer-manual.sgml,v 2.72 2016/07/26 10:45:49 fabiankeil
- Exp $<br>
- </p>
- <div>
- <div class="ABSTRACT">
- <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.26. You
- can find the latest version of the this manual at <a href=
- "https://www.privoxy.org/developer-manual/" target=
- "_top">https://www.privoxy.org/developer-manual/</a>. Please
- have a look at the <a href=
- "https://www.privoxy.org/user-manual/contact.html" target=
- "_top">contact section in the user manual</a> if you are
- interested in contacting the developers.
- </p>
- </div>
+<head>
+ <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">
+</head>
+
+<body class="ARTICLE" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
+"#840084" alink="#0000FF">
+ <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=
+ "https://www.privoxy.org/user-manual/copyright.html" target=
+ "_top">Copyright</a> © 2001-2016 by <a href=
+ "https://www.privoxy.org/" target="_top">Privoxy
+ Developers</a></sub><br></p>
+
+ <p class="PUBDATE">$Id: developer-manual.sgml,v 2.78 2016/08/25
+ 19:53:28 ler762 Exp $<br></p>
+
+ <div>
+ <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.26. You can find
+ the latest version of the this manual at <a href=
+ "https://www.privoxy.org/developer-manual/" target=
+ "_top">https://www.privoxy.org/developer-manual/</a>. Please have a
+ look at the <a href=
+ "https://www.privoxy.org/user-manual/contact.html" target=
+ "_top">contact section in the user manual</a> if you are interested
+ in contacting the developers.</p>
</div>
- <hr>
- </div>
- <div class="TOC">
- <dl>
- <dt>
- <b>Table of Contents</b>
- </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#AEN207">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#S40">Don't mix size_t and
- other types</a>
- </dt>
- <dt>
- 4.7.5. <a href="coding.html#S41">Declare each variable
- and struct on its own line.</a>
- </dt>
- <dt>
- 4.7.6. <a href="coding.html#S42">Use malloc/zalloc
- sparingly</a>
- </dt>
- <dt>
- 4.7.7. <a href="coding.html#S43">The Programmer Who Uses
- 'malloc' is Responsible for Ensuring 'free'</a>
- </dt>
- <dt>
- 4.7.8. <a href="coding.html#S44">Add loaders to the
- `file_list' structure and in order</a>
- </dt>
- <dt>
- 4.7.9. <a href="coding.html#S45">"Uncertain" new code
- and/or changes to existing code, use 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>
- </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>
- </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>
- </dl>
</div>
+ <hr>
</div>
- <div class="NAVFOOTER">
- <hr align="LEFT" 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 class="TOC">
+ <dl>
+ <dt><b>Table of Contents</b></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#AEN207">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#S40">Don't mix size_t and
+ other types</a></dt>
+
+ <dt>4.7.5. <a href="coding.html#S41">Declare each variable
+ and struct on its own line.</a></dt>
+
+ <dt>4.7.6. <a href="coding.html#S42">Use malloc/zalloc
+ sparingly</a></dt>
+
+ <dt>4.7.7. <a href="coding.html#S43">The Programmer Who Uses
+ 'malloc' is Responsible for Ensuring 'free'</a></dt>
+
+ <dt>4.7.8. <a href="coding.html#S44">Add loaders to the
+ `file_list' structure and in order</a></dt>
+
+ <dt>4.7.9. <a href="coding.html#S45">"Uncertain" new code
+ and/or changes to existing code, use 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>
+ </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>
+ </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>
+ </dl>
</div>
- </body>
-</html>
+ </div>
+
+ <div class="NAVFOOTER">
+ <hr align="left" 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>
- <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">
- </head>
- <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
- "#840084" alink="#0000FF">
- <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 align="LEFT" width="100%">
- </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=
- "https://lists.privoxy.org/mailman/listinfo/privoxy-devel" target=
- "_top">privoxy-devel 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 align="LEFT" 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>
+<head>
+ <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">
+</head>
+
+<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
+"#840084" alink="#0000FF">
+ <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 align="left" 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=
+ "https://lists.privoxy.org/mailman/listinfo/privoxy-devel" target=
+ "_top">privoxy-devel 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 align="left" 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>
- <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">
- </head>
- <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
- "#840084" alink="#0000FF">
- <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>
+<head>
+ <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">
+</head>
+
+<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
+"#840084" alink="#0000FF">
+ <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 align="left" 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"><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>
+ </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"><i class="EMPHASIS">must be
+ done by one of the developers</i></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>Update the code status (CODE_STATUS="xxx") in <tt class=
+ "FILENAME">configure.in</tt> to one of "alpha", "beta" or
+ "stable".</p>
+ </li>
+
+ <li>
+ <p>If action file processing has changed and is not
+ backward-compatable, make sure the "for-privoxy-version=x.y.z"
+ minimum version number in default.action.master has been
+ updated:</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+{{settings}}
+#############################################################################
+#MASTER# COMMENT: The minimum Privoxy version:
+for-privoxy-version=3.0.11
+</pre>
+ </td>
+ </tr>
+ </table>
+ </li>
+
+ <li>
+ <p>Update the sgml documentation source files with the version
+ number</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+<!entity p-version "3.0.26">
+</pre>
+ </td>
+ </tr>
+ </table>and set the code status
+
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+<!entity p-status "stable">
+</pre>
+ </td>
+ </tr>
+ </table>to one of "alpha", "beta" or "stable" in
+
+ <table border="0" bgcolor="#E0E0E0" width="90%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+ current/doc/source/authors.sgml
+ current/doc/source/config.sgml
+ current/doc/source/developer-manual.sgml
+ current/doc/source/faq.sgml
+ current/doc/source/install.sgml
+ current/doc/source/privoxy-man-page.sgml
+ current/doc/source/readme.sgml
+ current/doc/source/user-manual.sgml
+and in
+ current/doc/source/webserver/index.sgml
+</pre>
+ </td>
+ </tr>
+ </table>
+ </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) 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"><i class="EMPHASIS">Commit all files that
+ were changed in the above steps!</i></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"><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>
+
+ <table border="0" bgcolor="#E0E0E0" 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 align="LEFT" width="100%">
- </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"><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>
- <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"><i class=
+ "EMPHASIS">all</i></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"><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>
- 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) 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>
+
+ <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"><i class="EMPHASIS">make sure that
+ you have freshly exported the right version into an empty
+ directory</i></span>. (See "Building and releasing packages" above).
+ Then run:</p>
+
<table border="0" bgcolor="#E0E0E0" 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
- 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="SECT3">
- <h3 class="SECT3">
- <a name="NEWRELEASE-TARBALL">6.3.2. Source Tarball</a>
- </h3>
- <p>
- First, <span class="emphasis"><i class="EMPHASIS">make sure that
- you have freshly exported the right version into an empty
- directory</i></span>. (See "Building and releasing packages"
- above). Then run:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
- cd current
- autoheader && autoconf && ./configure
-</pre>
- </td>
- </tr>
- </table>
+ <p>Then do:</p>
- <p>
- Then do:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
make tarball-dist
</pre>
- </td>
- </tr>
- </table>
+ </td>
+ </tr>
+ </table>
- <p>
- To upload the package to Sourceforge, simply issue
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ <p>To upload the package to Sourceforge, simply issue</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
make tarball-upload
</pre>
- </td>
- </tr>
- </table>
+ </td>
+ </tr>
+ </table>
- <p>
- Go to the displayed URL and release the file publicly on
- Sourceforge. For the change log field, use the relevant section
- of the <tt class="FILENAME">ChangeLog</tt> file.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="NEWRELEASE-RPM">6.3.3. SuSE, Conectiva or Red Hat
- RPM</a>
- </h3>
- <p>
- In following text, replace <tt class=
- "REPLACEABLE"><i>dist</i></tt> with either <span class=
- "QUOTE">"rh"</span> for Red Hat or <span class=
- "QUOTE">"suse"</span> for SuSE.
- </p>
- <p>
- First, <span class="emphasis"><i class="EMPHASIS">make sure that
- you have freshly exported the right version into an empty
- directory</i></span>. (See "Building and releasing packages"
- above).
- </p>
- <p>
- As the only exception to not changing anything after export from
- CVS, now examine the file <tt class="FILENAME">privoxy-</tt><tt
- class="REPLACEABLE"><i>dist</i></tt><tt class=
- "FILENAME">.spec</tt> and make sure that the version information
- and the RPM release number are correct. The RPM release numbers
- for each version start at one. Hence it must be reset to one if
- this is the first RPM for <tt class=
- "REPLACEABLE"><i>dist</i></tt> which is built from version X.Y.Z.
- Check the <a href=
- "https://sourceforge.net/project/showfiles.php?group_id=11118"
- target="_top">file list</a> if unsure. Else, it must be set to
- the highest already available RPM release number for that version
- plus one.
- </p>
- <p>
- Then run:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ <p>Go to the displayed URL and release the file publicly on
+ Sourceforge. For the change log field, use the relevant section of
+ the <tt class="FILENAME">ChangeLog</tt> file.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="NEWRELEASE-RPM" id="NEWRELEASE-RPM">6.3.3.
+ SuSE, Conectiva or Red Hat RPM</a></h3>
+
+ <p>In following text, replace <tt class=
+ "REPLACEABLE"><i>dist</i></tt> with either <span class=
+ "QUOTE">"rh"</span> for Red Hat or <span class="QUOTE">"suse"</span>
+ for SuSE.</p>
+
+ <p>First, <span class="emphasis"><i class="EMPHASIS">make sure that
+ you have freshly exported the right version into an empty
+ directory</i></span>. (See "Building and releasing packages"
+ above).</p>
+
+ <p>As the only exception to not changing anything after export from
+ CVS, now examine the file <tt class=
+ "FILENAME">privoxy-</tt><tt class="REPLACEABLE"><i>dist</i></tt><tt class="FILENAME">.spec</tt>
+ and make sure that the version information and the RPM release number
+ are correct. The RPM release numbers for each version start at one.
+ Hence it must be reset to one if this is the first RPM for <tt class=
+ "REPLACEABLE"><i>dist</i></tt> which is built from version X.Y.Z.
+ Check the <a href=
+ "https://sourceforge.net/project/showfiles.php?group_id=11118"
+ target="_top">file list</a> if unsure. Else, it must be set to the
+ highest already available RPM release number for that version plus
+ one.</p>
+
+ <p>Then run:</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
cd current
autoheader && autoconf && ./configure
</pre>
- </td>
- </tr>
- </table>
+ </td>
+ </tr>
+ </table>
- <p>
- Then do
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ <p>Then do</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
make <tt class="REPLACEABLE"><i>dist</i></tt>-dist
</pre>
- </td>
- </tr>
- </table>
+ </td>
+ </tr>
+ </table>
- <p>
- To upload the package to Sourceforge, simply issue
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ <p>To upload the package to Sourceforge, simply issue</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
make <tt class="REPLACEABLE"><i>dist</i></tt>-upload <tt class=
"REPLACEABLE"><i>rpm_packagerev</i></tt>
</pre>
- </td>
- </tr>
- </table>
+ </td>
+ </tr>
+ </table>
- <p>
- where <tt class="REPLACEABLE"><i>rpm_packagerev</i></tt> is the
- RPM release number as determined above. Go to the displayed URL
- and release the file publicly on Sourceforge. Use the release
- notes and change log from the source tarball package.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="NEWRELEASE-OS2">6.3.4. OS/2</a>
- </h3>
- <p>
- First, <span class="emphasis"><i class="EMPHASIS">make sure that
- you have freshly exported the right version into an empty
- directory</i></span>. (See "Building and releasing packages"
- above). Then get the OS/2 Setup module:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ <p>where <tt class="REPLACEABLE"><i>rpm_packagerev</i></tt> is the
+ RPM release number as determined above. Go to the displayed URL and
+ release the file publicly on Sourceforge. Use the release notes and
+ change log from the source tarball package.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="NEWRELEASE-OS2" id="NEWRELEASE-OS2">6.3.4.
+ OS/2</a></h3>
+
+ <p>First, <span class="emphasis"><i class="EMPHASIS">make sure that
+ you have freshly exported the right version into an empty
+ directory</i></span>. (See "Building and releasing packages" above).
+ Then get the OS/2 Setup module:</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup
</pre>
- </td>
- </tr>
- </table>
+ </td>
+ </tr>
+ </table>
- <p>
- You will need a mix of development tools. The main compilation
- takes place with IBM Visual Age C++. Some ancillary work takes
- place with GNU tools, available from various sources like
- hobbes.nmsu.edu. Specificially, you will need <tt class=
- "FILENAME">autoheader</tt>, <tt class="FILENAME">autoconf</tt>
- and <tt class="FILENAME">sh</tt> tools. The packaging takes place
- with WarpIN, available from various sources, including its home
- page: <a href="http://www.xworkplace.org/" target=
- "_top">xworkplace</a>.
- </p>
- <p>
- Change directory to the <tt class="FILENAME">os2setup</tt>
- directory. Edit the os2build.cmd file to set the final executable
- filename. For example,
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ <p>You will need a mix of development tools. The main compilation
+ takes place with IBM Visual Age C++. Some ancillary work takes place
+ with GNU tools, available from various sources like hobbes.nmsu.edu.
+ Specificially, you will need <tt class="FILENAME">autoheader</tt>,
+ <tt class="FILENAME">autoconf</tt> and <tt class="FILENAME">sh</tt>
+ tools. The packaging takes place with WarpIN, available from various
+ sources, including its home page: <a href=
+ "http://www.xworkplace.org/" target="_top">xworkplace</a>.</p>
+
+ <p>Change directory to the <tt class="FILENAME">os2setup</tt>
+ directory. Edit the os2build.cmd file to set the final executable
+ filename. For example,</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
installExeName='privoxyos2_setup_X.Y.Z.exe'
</pre>
- </td>
- </tr>
- </table>
+ </td>
+ </tr>
+ </table>
- <p>
- Next, edit the <tt class="FILENAME">IJB.wis</tt> file so the
- release number matches in the <tt class="FILENAME">PACKAGEID</tt>
- section:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ <p>Next, edit the <tt class="FILENAME">IJB.wis</tt> file so the
+ release number matches in the <tt class="FILENAME">PACKAGEID</tt>
+ section:</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"
</pre>
- </td>
- </tr>
- </table>
+ </td>
+ </tr>
+ </table>
- <p>
- You're now ready to build. Run:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ <p>You're now ready to build. Run:</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
os2build
</pre>
- </td>
- </tr>
- </table>
+ </td>
+ </tr>
+ </table>
- <p>
- You will find the WarpIN-installable executable in the <tt class=
- "FILENAME">./files</tt> directory. Upload this anonymously to <tt
- class="FILENAME">uploads.sourceforge.net/incoming</tt>, create a
- release for it, and you're done. Use the release notes and Change
- Log from the source tarball package.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="NEWRELEASE-SOLARIS">6.3.5. Solaris</a>
- </h3>
- <p>
- Login to Sourceforge's compilefarm via ssh:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ <p>You will find the WarpIN-installable executable in the <tt class=
+ "FILENAME">./files</tt> directory. Upload this anonymously to
+ <tt class="FILENAME">uploads.sourceforge.net/incoming</tt>, create a
+ release for it, and you're done. Use the release notes and Change Log
+ from the source tarball package.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="NEWRELEASE-SOLARIS" id=
+ "NEWRELEASE-SOLARIS">6.3.5. Solaris</a></h3>
+
+ <p>Login to Sourceforge's compilefarm via ssh:</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
ssh cf.sourceforge.net
</pre>
- </td>
- </tr>
- </table>
+ </td>
+ </tr>
+ </table>
- <p>
- Choose the right operating system (not the Debian one). When
- logged in, <span class="emphasis"><i class="EMPHASIS">make sure
- that you have freshly exported the right version into an empty
- directory</i></span>. (See "Building and releasing packages"
- above). Then run:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ <p>Choose the right operating system (not the Debian one). When
+ logged in, <span class="emphasis"><i class="EMPHASIS">make sure that
+ you have freshly exported the right version into an empty
+ directory</i></span>. (See "Building and releasing packages" above).
+ Then run:</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
cd current
autoheader && autoconf && ./configure
</pre>
- </td>
- </tr>
- </table>
+ </td>
+ </tr>
+ </table>
- <p>
- Then run
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ <p>Then run</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
gmake solaris-dist
</pre>
- </td>
- </tr>
- </table>
+ </td>
+ </tr>
+ </table>
- <p>
- which creates a gzip'ed tar archive. Sadly, you cannot use <b
- class="COMMAND">make solaris-upload</b> on the Sourceforge
- machine (no ncftpput). You now have to manually upload the
- archive to Sourceforge's ftp server and release the file
- publicly. Use the release notes and Change Log from the source
- tarball package.
- </p>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="NEWRELEASE-WINDOWS">6.3.6. Windows</a>
- </h3>
- <p>
- Use the <a href=
- "http://www.fruitbat.org/Cygwin/index.html#cygwincirca" target=
- "_top">Cygwin Time Machine</a> to install the last 1.5 version of
- Cygwin. Run the following commands from within the Cygwin 1.5
- bash shell.
- </p>
- <p>
- First, <span class="emphasis"><i class="EMPHASIS">make sure that
- you have freshly exported the right version into an empty
- directory</i></span>. (See "Building and releasing packages"
- above). Then get the Windows setup module:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ <p>which creates a gzip'ed tar archive. Sadly, you cannot use
+ <b class="COMMAND">make solaris-upload</b> on the Sourceforge machine
+ (no ncftpput). You now have to manually upload the archive to
+ Sourceforge's ftp server and release the file publicly. Use the
+ release notes and Change Log from the source tarball package.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="NEWRELEASE-WINDOWS" id=
+ "NEWRELEASE-WINDOWS">6.3.6. Windows</a></h3>
+
+ <p>Use the <a href=
+ "http://www.fruitbat.org/Cygwin/index.html#cygwincirca" target=
+ "_top">Cygwin Time Machine</a> to install the last 1.5 version of
+ Cygwin. Run the following commands from within the Cygwin 1.5 bash
+ shell.</p>
+
+ <p>First, <span class="emphasis"><i class="EMPHASIS">make sure that
+ you have freshly exported the right version into an empty
+ directory</i></span>. (See "Building and releasing packages" above).
+ Then get the Windows setup module:</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup
</pre>
- </td>
- </tr>
- </table>
+ </td>
+ </tr>
+ </table>
+
+ <p>Then you can build the package. This is fully automated, and is
+ controlled by <tt class="FILENAME">winsetup/GNUmakefile</tt>. All you
+ need to do is:</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+ cd winsetup
+ make
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>Now you can manually rename <tt class=
+ "FILENAME">privoxy_setup.exe</tt> to <tt class=
+ "FILENAME">privoxy_setup_X_Y_Z.exe</tt>, and upload it to
+ SourceForge. When releasing the package on SourceForge, use the
+ release notes and Change Log from the source tarball package.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="NEWRELEASE-DEBIAN" id=
+ "NEWRELEASE-DEBIAN">6.3.7. Debian</a></h3>
+
+ <p>First, <span class="emphasis"><i class="EMPHASIS">make sure that
+ you have freshly exported the right version into an empty
+ directory</i></span>. (See "Building and releasing packages" above).
+ Then add a log entry to <tt class="FILENAME">debian/changelog</tt>,
+ if it is not already there, for example by running:</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+ debchange -v 3.0.26-stable-1 "New upstream version"
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>Then, run:</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+ dpkg-buildpackage -rfakeroot -us -uc -b
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>This will create <tt class=
+ "FILENAME">../privoxy_3.0.26-stable-1_i386.deb</tt> which can be
+ uploaded. To upload the package to Sourceforge, simply issue</p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+ make debian-upload
+</pre>
+ </td>
+ </tr>
+ </table>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="NEWRELEASE-MACOSX" id=
+ "NEWRELEASE-MACOSX">6.3.8. Mac OS X</a></h3>
+
+ <p>First, <span class="emphasis"><i class="EMPHASIS">make sure that
+ you have freshly exported the right version into an empty
+ directory</i></span>. (See "Building and releasing packages"
+ above).</p>
+
+ <p>There are three modules available in the CVS repository for use on
+ Mac OS X, though technically only two of them generate a release (the
+ other can be used to install from source).</p>
+
+ <div class="SECT4">
+ <h4 class="SECT4"><a name="OS-X-OSXPACKAGEBUILDER-MODULE" id=
+ "OS-X-OSXPACKAGEBUILDER-MODULE">6.3.8.1. OSXPackageBuilder
+ module</a></h4>
+
+ <p>The OSXPackageBuilder module generates OS X installer packages
+ supporting all Macs running OS X 10.4 and above. Obtain it from CVS
+ as follows into a folder parallel to the exported privoxy
+ source:</p>
- <p>
- Then you can build the package. This is fully automated, and is
- controlled by <tt class="FILENAME">winsetup/GNUmakefile</tt>. All
- you need to do is:
- </p>
- <p>
- </p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
-<pre class="PROGRAMLISTING">
- cd winsetup
- make
+ <pre class="PROGRAMLISTING">
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co OSXPackageBuilder
</pre>
</td>
</tr>
</table>
- <p>
- Now you can manually rename <tt class=
- "FILENAME">privoxy_setup.exe</tt> to <tt class=
- "FILENAME">privoxy_setup_X_Y_Z.exe</tt>, and upload it to
- SourceForge. When releasing the package on SourceForge, use the
- release notes and Change Log from the source tarball package.
- </p>
+ <p>The module contains complete instructions on its usage in the
+ file <tt class="FILENAME">OS X Package Builder HOWTO.txt</tt>.</p>
+
+ <p>Once the package(s) have been generated, you can then upload
+ them directly to the Files section of the Sourceforge project in
+ the Macintosh (OS X) folder. Each new version release of Privoxy
+ should have a new subfolder created in which to store its files.
+ Please ensure that the folder contains a readme file that makes it
+ clear which package is for whichversion of OS X.</p>
</div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="NEWRELEASE-DEBIAN">6.3.7. Debian</a>
- </h3>
- <p>
- First, <span class="emphasis"><i class="EMPHASIS">make sure that
- you have freshly exported the right version into an empty
- directory</i></span>. (See "Building and releasing packages"
- above). Then add a log entry to <tt class=
- "FILENAME">debian/changelog</tt>, if it is not already there, for
- example by running:
- </p>
- <p>
- </p>
+
+ <div class="SECT4">
+ <h4 class="SECT4"><a name="OS-X-OSXSETUP-MODULE" id=
+ "OS-X-OSXSETUP-MODULE">6.3.8.2. osxsetup module
+ (DEPRECATED)</a></h4>
+
+ <p><span class="emphasis"><i class="EMPHASIS">This module is
+ deprecated since the installer it generates places all Privoxy
+ files in one folder in a non-standard location, and supports only
+ Intel Macs running OS X 10.6 or higher.</i></span></p>
+
+ <p>Check out the module from CVS as follows into a folder parallel
+ to the exported privoxy source:</p>
+
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
-<pre class="PROGRAMLISTING">
- debchange -v 3.0.26-UNRELEASED-1 "New upstream version"
+
<pre class="PROGRAMLISTING">
+ cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup
</pre>
</td>
</tr>
</table>
- <p>
- Then, run:
- </p>
- <p>
- </p>
+ <p>Then run:</p>
+
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
-<pre class="PROGRAMLISTING">
- dpkg-buildpackage -rfakeroot -us -uc -b
+ <pre class="PROGRAMLISTING">
+ cd osxsetup
+ build
</pre>
</td>
</tr>
</table>
- <p>
- This will create <tt class=
- "FILENAME">../privoxy_3.0.26-UNRELEASED-1_i386.deb</tt> which can
- be uploaded. To upload the package to Sourceforge, simply issue
- </p>
- <p>
- </p>
+ <p>This will run <tt class="FILENAME">autoheader</tt>, <tt class=
+ "FILENAME">autoconf</tt> and <tt class="FILENAME">configure</tt> as
+ well as <tt class="FILENAME">make</tt>. Finally, it will copy over
+ the necessary files to the ./osxsetup/files directory for further
+ processing by <tt class="FILENAME">PackageMaker</tt>.</p>
+
+ <p>Bring up PackageMaker with the PrivoxyPackage.pmsp definition
+ file, modify the package name to match the release, and hit the
+ "Create package" button. If you specify ./Privoxy.pkg as the output
+ package name, you can then create the distributable zip file with
+ the command:</p>
+
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
-<pre class="PROGRAMLISTING">
- make debian-upload
+
<pre class="PROGRAMLISTING">
+ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
</pre>
</td>
</tr>
</table>
+
+ <p>You can then upload this file directly to the Files section of
+ the Sourceforge project in the Macintosh (OS X) folder. Each new
+ version release of Privoxy should have a new subfolder created in
+ which to store its files. Please ensure that the folder contains a
+ readme file that makes it clear which version(s) of OS X the
+ package supports.</p>
</div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="NEWRELEASE-MACOSX">6.3.8. Mac OS X</a>
- </h3>
- <p>
- First, <span class="emphasis"><i class="EMPHASIS">make sure that
- you have freshly exported the right version into an empty
- directory</i></span>. (See "Building and releasing packages"
- above).
- </p>
- <p>
- There are three modules available in the CVS repository for use
- on Mac OS X, though technically only two of them generate a
- release (the other can be used to install from source).
- </p>
- <div class="SECT4">
- <h4 class="SECT4">
- <a name="OS-X-OSXPACKAGEBUILDER-MODULE">6.3.8.1.
- OSXPackageBuilder module</a>
- </h4>
- <p>
- The OSXPackageBuilder module generates OS X installer packages
- supporting all Macs running OS X 10.4 and above. Obtain it from
- CVS as follows into a folder parallel to the exported privoxy
- source:
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
- cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co OSXPackageBuilder
-</pre>
- </td>
- </tr>
- </table>
- <p>
- The module contains complete instructions on its usage in the
- file <tt class="FILENAME">OS X Package Builder HOWTO.txt</tt>.
- </p>
- <p>
- Once the package(s) have been generated, you can then upload
- them directly to the Files section of the Sourceforge project
- in the Macintosh (OS X) folder. Each new version release of
- Privoxy should have a new subfolder created in which to store
- its files. Please ensure that the folder contains a readme file
- that makes it clear which package is for whichversion of OS X.
- </p>
- </div>
- <div class="SECT4">
- <h4 class="SECT4">
- <a name="OS-X-OSXSETUP-MODULE">6.3.8.2. osxsetup module
- (DEPRECATED)</a>
- </h4>
- <p>
- <span class="emphasis"><i class="EMPHASIS">This module is
- deprecated since the installer it generates places all Privoxy
- files in one folder in a non-standard location, and supports
- only Intel Macs running OS X 10.6 or higher.</i></span>
- </p>
- <p>
- Check out the module from CVS as follows into a folder parallel
- to the exported privoxy source:
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
- cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup
-</pre>
- </td>
- </tr>
- </table>
+ <div class="SECT4">
+ <h4 class="SECT4"><a name="OS-X-MACSETUP-MODULE" id=
+ "OS-X-MACSETUP-MODULE">6.3.8.3. macsetup module</a></h4>
- <p>
- Then run:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
- cd osxsetup
- build
-</pre>
- </td>
- </tr>
- </table>
+ <p>The macsetup module is ideal if you wish to build and install
+ Privoxy from source on a single machine.</p>
- <p>
- This will run <tt class="FILENAME">autoheader</tt>, <tt class=
- "FILENAME">autoconf</tt> and <tt class=
- "FILENAME">configure</tt> as well as <tt class=
- "FILENAME">make</tt>. Finally, it will copy over the necessary
- files to the ./osxsetup/files directory for further processing
- by <tt class="FILENAME">PackageMaker</tt>.
- </p>
- <p>
- Bring up PackageMaker with the PrivoxyPackage.pmsp definition
- file, modify the package name to match the release, and hit the
- "Create package" button. If you specify ./Privoxy.pkg as the
- output package name, you can then create the distributable zip
- file with the command:
- </p>
- <p>
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
- zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg
-</pre>
- </td>
- </tr>
- </table>
+ <p>Check out the module from CVS as follows into a folder parallel
+ to the exported privoxy source:</p>
- <p>
- You can then upload this file directly to the Files section of
- the Sourceforge project in the Macintosh (OS X) folder. Each
- new version release of Privoxy should have a new subfolder
- created in which to store its files. Please ensure that the
- folder contains a readme file that makes it clear which
- version(s) of OS X the package supports.
- </p>
- </div>
- <div class="SECT4">
- <h4 class="SECT4">
- <a name="OS-X-MACSETUP-MODULE">6.3.8.3. macsetup module</a>
- </h4>
- <p>
- The macsetup module is ideal if you wish to build and install
- Privoxy from source on a single machine.
- </p>
- <p>
- Check out the module from CVS as follows into a folder parallel
- to the exported privoxy source:
- </p>
- <table border="0" bgcolor="#E0E0E0" width="100%">
- <tr>
- <td>
-<pre class="PROGRAMLISTING">
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co macsetup
</pre>
- </td>
- </tr>
- </table>
+ </td>
+ </tr>
+ </table>
- <p>
- The module contains complete instructions on its usage in its
- <tt class="FILENAME">README</tt> file. The end result will be
- the exported version of Privoxy installed on the build machine.
- </p>
- </div>
- </div>
- <div class="SECT3">
- <h3 class="SECT3">
- <a name="NEWRELEASE-FREEBSD">6.3.9. FreeBSD</a>
- </h3>
- <p>
- Update the www/privoxy port and submit a diff upstream. For
- details see the <a href=
- "https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/"
- target="_top">FreeBSD Porter's Handbook</a>.
- </p>
+ <p>The module contains complete instructions on its usage in its
+ <tt class="FILENAME">README</tt> file. The end result will be the
+ exported version of Privoxy installed on the build machine.</p>
</div>
</div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="RELEASING">6.4. Uploading and Releasing Your Package</a>
- </h2>
- <p>
- After the package is ready, it is time to upload it to SourceForge,
- and go through the release steps. The upload is done via FTP:
- </p>
- <p>
- </p>
- <ul>
- <li>
- <p>
- Upload to: <a href="ftp://upload.sourceforge.net/incoming"
- target="_top">ftp://upload.sourceforge.net/incoming</a>
- </p>
- </li>
- <li>
- <p>
- user: <tt class="LITERAL">anonymous</tt>
- </p>
- </li>
- <li>
- <p>
- password: <tt class=
- "LITERAL">ijbswa-developers@lists.sourceforge.net</tt>
- </p>
- </li>
- </ul>
- <p>
- Or use the <b class="COMMAND">make</b> targets as described above.
- </p>
- <p>
- Once this done go to <a href=
- "https://sourceforge.net/project/admin/editpackages.php?group_id=11118"
- target=
- "_top">https://sourceforge.net/project/admin/editpackages.php?group_id=11118</a>,
- making sure you are logged in. Find your target platform in the
- second column, and click <tt class="LITERAL">Add Release</tt>. You
- will then need to create a new release for your package, using the
- format of <tt class="LITERAL">$VERSION ($CODE_STATUS)</tt>, e.g.
- <span class="emphasis"><i class="EMPHASIS">3.0.26
- (beta)</i></span>.
- </p>
- <p>
- Now just follow the prompts. Be sure to add any appropriate Release
- notes. You should see your freshly uploaded packages in <span
- class="QUOTE">"Step 2. Add Files To This Release"</span>. Check the
- appropriate box(es). Remember at each step to hit the <span class=
- "QUOTE">"Refresh/Submit"</span> buttons! You should now see your
- file(s) listed in Step 3. Fill out the forms with the appropriate
- information for your platform, being sure to hit <span class=
- "QUOTE">"Update"</span> for each file. If anyone is monitoring your
- platform, check the <span class="QUOTE">"email"</span> box at the
- very bottom to notify them of the new package. This should do it!
- </p>
- <p>
- If you have made errors, or need to make changes, you can go
- through essentially the same steps, but select <tt class=
- "LITERAL">Edit Release</tt>, instead of <tt class="LITERAL">Add
- Release</tt>.
- </p>
- </div>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="AFTERRELEASE">6.5. After the Release</a>
- </h2>
- <p>
- When all (or: most of the) packages have been uploaded and made
- available, send an email to the <a href=
- "mailto:privoxy-announce@lists.privoxy.org" target="_top">announce
- mailing list</a>, Subject: "Version X.Y.Z available for download".
- Be sure to include the <a href=
- "https://sourceforge.net/project/showfiles.php?group_id=11118"
- target="_top">download location</a>, the release notes and the
- Changelog. Also, post an updated News item on the project page
- Sourceforge, and update the Home page and docs linked from the Home
- page (see below). Other news sites and release oriented sites, such
- as Freshmeat, should also be notified.
- </p>
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="NEWRELEASE-FREEBSD" id=
+ "NEWRELEASE-FREEBSD">6.3.9. FreeBSD</a></h3>
+
+ <p>Update the www/privoxy port and submit a diff upstream. For
+ details see the <a href=
+ "https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/"
+ target="_top">FreeBSD Porter's Handbook</a>.</p>
</div>
</div>
- <div class="NAVFOOTER">
- <hr align="LEFT" 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="testing.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="webserver-update.html" accesskey="N">Next</a>
- </td>
- </tr>
- <tr>
- <td width="33%" align="left" valign="top">
- Testing Guidelines
- </td>
- <td width="34%" align="center" valign="top">
-
- </td>
- <td width="33%" align="right" valign="top">
- Update the Webserver
- </td>
- </tr>
- </table>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="RELEASING" id="RELEASING">6.4. Uploading and
+ Releasing Your Package</a></h2>
+
+ <p>After the package is ready, it is time to upload it to SourceForge,
+ and go through the release steps. The upload is done via FTP:</p>
+
+ <ul>
+ <li>
+ <p>Upload to: <a href="ftp://upload.sourceforge.net/incoming"
+ target="_top">ftp://upload.sourceforge.net/incoming</a></p>
+ </li>
+
+ <li>
+ <p>user: <tt class="LITERAL">anonymous</tt></p>
+ </li>
+
+ <li>
+ <p>password: <tt class=
+ "LITERAL">ijbswa-developers@lists.sourceforge.net</tt></p>
+ </li>
+ </ul>
+
+ <p>Or use the <b class="COMMAND">make</b> targets as described
+ above.</p>
+
+ <p>Once this done go to <a href=
+ "https://sourceforge.net/project/admin/editpackages.php?group_id=11118"
+ target=
+ "_top">https://sourceforge.net/project/admin/editpackages.php?group_id=11118</a>,
+ making sure you are logged in. Find your target platform in the second
+ column, and click <tt class="LITERAL">Add Release</tt>. You will then
+ need to create a new release for your package, using the format of
+ <tt class="LITERAL">$VERSION ($CODE_STATUS)</tt>, e.g. <span class=
+ "emphasis"><i class="EMPHASIS">3.0.26 (beta)</i></span>.</p>
+
+ <p>Now just follow the prompts. Be sure to add any appropriate Release
+ notes. You should see your freshly uploaded packages in <span class=
+ "QUOTE">"Step 2. Add Files To This Release"</span>. Check the
+ appropriate box(es). Remember at each step to hit the <span class=
+ "QUOTE">"Refresh/Submit"</span> buttons! You should now see your
+ file(s) listed in Step 3. Fill out the forms with the appropriate
+ information for your platform, being sure to hit <span class=
+ "QUOTE">"Update"</span> for each file. If anyone is monitoring your
+ platform, check the <span class="QUOTE">"email"</span> box at the very
+ bottom to notify them of the new package. This should do it!</p>
+
+ <p>If you have made errors, or need to make changes, you can go through
+ essentially the same steps, but select <tt class="LITERAL">Edit
+ Release</tt>, instead of <tt class="LITERAL">Add Release</tt>.</p>
</div>
- </body>
-</html>
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="AFTERRELEASE" id="AFTERRELEASE">6.5. After
+ the Release</a></h2>
+
+ <p>When all (or: most of the) packages have been uploaded and made
+ available, send an email to the <a href=
+ "mailto:privoxy-announce@lists.privoxy.org" target="_top">announce
+ mailing list</a>, Subject: "Version X.Y.Z available for download". Be
+ sure to include the <a href=
+ "https://sourceforge.net/project/showfiles.php?group_id=11118" target=
+ "_top">download location</a>, the release notes and the Changelog.
+ Also, post an updated News item on the project page Sourceforge, and
+ update the Home page and docs linked from the Home page (see below).
+ Other news sites and release oriented sites, such as Freshmeat, should
+ also be notified.</p>
+ </div>
+ </div>
+
+ <div class="NAVFOOTER">
+ <hr align="left" 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="testing.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=
+ "webserver-update.html" accesskey="N">Next</a></td>
+ </tr>
+
+ <tr>
+ <td width="33%" align="left" valign="top">Testing Guidelines</td>
+
+ <td width="34%" align="center" valign="top"> </td>
+
+ <td width="33%" align="right" valign="top">Update the Webserver</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>
- <title>
- Testing 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="Coding Guidelines" href="coding.html">
- <link rel="NEXT" title="Releasing a New Version" href="newrelease.html">
- <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
- </head>
- <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
- "#840084" alink="#0000FF">
- <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="coding.html" accesskey="P">Prev</a>
- </td>
- <td width="80%" align="center" valign="bottom">
- </td>
- <td width="10%" align="right" valign="bottom">
- <a href="newrelease.html" accesskey="N">Next</a>
- </td>
- </tr>
- </table>
- <hr align="LEFT" width="100%">
- </div>
- <div class="SECT1">
- <h1 class="SECT1">
- <a name="TESTING">5. Testing Guidelines</a>
- </h1>
- <p>
- To be filled.
- </p>
- <div class="SECT2">
- <h2 class="SECT2">
- <a name="TESTING-PLAN">5.1. Testplan for releases</a>
- </h2>
- <p>
- Explain release numbers. major, minor. developer releases. etc.
- </p>
- <ol type="1">
- <li>
- <p>
- Remove any existing rpm with rpm -e
- </p>
- </li>
- <li>
- <p>
- Remove any file that was left over. This includes (but is not
- limited to)
- </p>
- <ul>
- <li>
- <p>
- /var/log/privoxy
- </p>
- </li>
- <li>
- <p>
- /etc/privoxy
- </p>
- </li>
- <li>
- <p>
- /usr/sbin/privoxy
- </p>
- </li>
- <li>
- <p>
- /etc/init.d/privoxy
- </p>
- </li>
- <li>
- <p>
- /usr/doc/privoxy*
- </p>
- </li>
- </ul>
- </li>
- <li>
- <p>
- Install the rpm. Any error messages?
- </p>
- </li>
- <li>
- <p>
- start,stop,status <span class="APPLICATION">Privoxy</span> with
- the specific script (e.g. /etc/rc.d/init/privoxy stop). Reboot
- your machine. Does autostart work?
- </p>
- </li>
- <li>
- <p>
- Start browsing. Does <span class="APPLICATION">Privoxy</span>
- work? Logfile written?
- </p>
- </li>
- <li>
- <p>
- Remove the rpm. Any error messages? All files removed?
- </p>
- </li>
- </ol>
- </div>
- </div>
- <div class="NAVFOOTER">
- <hr align="LEFT" 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="coding.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="newrelease.html" accesskey="N">Next</a>
- </td>
- </tr>
- <tr>
- <td width="33%" align="left" valign="top">
- Coding Guidelines
- </td>
- <td width="34%" align="center" valign="top">
-
- </td>
- <td width="33%" align="right" valign="top">
- Releasing a New Version
- </td>
- </tr>
- </table>
+<head>
+ <title>Testing 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="Coding Guidelines" href="coding.html">
+ <link rel="NEXT" title="Releasing a New Version" href="newrelease.html">
+ <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+</head>
+
+<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
+"#840084" alink="#0000FF">
+ <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="coding.html"
+ accesskey="P">Prev</a></td>
+
+ <td width="80%" align="center" valign="bottom"></td>
+
+ <td width="10%" align="right" valign="bottom"><a href=
+ "newrelease.html" accesskey="N">Next</a></td>
+ </tr>
+ </table>
+ <hr align="left" width="100%">
+ </div>
+
+ <div class="SECT1">
+ <h1 class="SECT1"><a name="TESTING" id="TESTING">5. Testing
+ Guidelines</a></h1>
+
+ <p>To be filled.</p>
+
+ <div class="SECT2">
+ <h2 class="SECT2"><a name="TESTING-PLAN" id="TESTING-PLAN">5.1.
+ Testplan for releases</a></h2>
+
+ <p>Explain release numbers. major, minor. developer releases. etc.</p>
+
+ <ol type="1">
+ <li>
+ <p>Remove any existing rpm with rpm -e</p>
+ </li>
+
+ <li>
+ <p>Remove any file that was left over. This includes (but is not
+ limited to)</p>
+
+ <ul>
+ <li>
+ <p>/var/log/privoxy</p>
+ </li>
+
+ <li>
+ <p>/etc/privoxy</p>
+ </li>
+
+ <li>
+ <p>/usr/sbin/privoxy</p>
+ </li>
+
+ <li>
+ <p>/etc/init.d/privoxy</p>
+ </li>
+
+ <li>
+ <p>/usr/doc/privoxy*</p>
+ </li>
+ </ul>
+ </li>
+
+ <li>
+ <p>Install the rpm. Any error messages?</p>
+ </li>
+
+ <li>
+ <p>start,stop,status <span class="APPLICATION">Privoxy</span> with
+ the specific script (e.g. /etc/rc.d/init/privoxy stop). Reboot your
+ machine. Does autostart work?</p>
+ </li>
+
+ <li>
+ <p>Start browsing. Does <span class="APPLICATION">Privoxy</span>
+ work? Logfile written?</p>
+ </li>
+
+ <li>
+ <p>Remove the rpm. Any error messages? All files removed?</p>
+ &n
projects / privoxy.git / commitdiff