/*********************************************************************
*
- * File : $Source: /cvsroot/ijbswa/current/INSTALL,v $
+ * File : $Source: /cvsroot/ijbswa/current/doc/source/install.sgml,v $
*
* Purpose : INSTALL file to help with installing from source.
*
When building from a source tarball, first unpack the source:
- tar xzvf privoxy-3.0.26-stable-src.tar.gz
- cd privoxy-3.0.26-stable
+ tar xzvf privoxy-3.0.27-beta-src.tar.gz
+ cd privoxy-3.0.27-beta
For retrieving the current CVS sources, you'll need a CVS client installed.
Note that sources from CVS are typically development quality, and may not be
/*********************************************************************
*
- * File : $Source: /cvsroot/ijbswa/current/README,v $
+ * File : $Source: /cvsroot/ijbswa/current/doc/source/readme.sgml,v $
*
* Purpose : README file to give a short intro.
*
*
*********************************************************************/
-This README is included with Privoxy 3.0.26. See https://www.privoxy.org/ for
-more information. The current code maturity level is "stable".
+This README is included with the development version of Privoxy 3.0.27. See
+https://www.privoxy.org/ for more information. The current code maturity level
+is "UNRELEASED", but seems stable to us :).
-------------------------------------------------------------------------------
The actions list can be configured via the web interface accessed via http://
p.p/, as well other options.
+All configuration files are subject to unannounced changes during the
+development process.
+
-------------------------------------------------------------------------------
5. DOCUMENTATION
-There should be documentation in the 'doc' subdirectory. In particular, see the
-User Manual there, the FAQ, and those interested in Privoxy development, should
-look at developer-manual.
+There should be documentation in the 'doc' subdirectory, but it may not be
+completed at this point. In particular, see the User Manual there, the FAQ, and
+those interested in Privoxy development, should look at developer-manual.
-The source and configuration files are all well commented. The main
-configuration files are: 'config', 'default.action', and 'default.filter'.
+The most up to date source of information on the current development version,
+may still be either comments in the source code, or the included configuration
+files. The source and configuration files are all well commented. The main
+configuration files are: 'config', 'default.action', and 'default.filter' in
+the top-level source directory.
Included documentation may vary according to platform and packager. All
documentation is posted on https://www.privoxy.org, in case you don't have it,
directive is being used and the following debug options are enabled (all of
them):
- debug 1 # Log the destination for each request Privoxy let through. See also debug 1024.
+ debug 1 # Log the destination for each request Privoxy let through.
+ # See also debug 1024.
debug 2 # show each connection status
debug 4 # show I/O status
debug 8 # show header parsing
debug 128 # debug redirects
debug 256 # debug GIF de-animation
debug 512 # Common Log Format
- debug 1024 # Log the destination for requests Privoxy didn't let through, and the reason why.
+ debug 1024 # Log the destination for requests Privoxy didn't let through,
+ # and the reason why.
debug 4096 # Startup banner and warnings.
debug 8192 # Non-fatal errors
+ debug 65536 # Log applying actions
If you are having trouble with a filter, please additionally enable
debug 64 # debug regular expression filters
- If you are using Privoxy 3.0.17 or later and suspect that it interprets the
- request or the response incorrectly, please enable
+ If you suspect that Privoxy interprets the request or the response
+ incorrectly, please enable
debug 32768 # log all data read from the network
<html>
<head>
<title>Coding Guidelines</title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
+ <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="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=utf-8">
</head>
-<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
-"#840084" alink="#0000FF">
+<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">
+ <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="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>
+ <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>
+ <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>
+ <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" 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>
+ <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 ... */
+ <pre class="PROGRAMLISTING">/* if page size greater than 1k ... */
if (page_length() > 1024)
{
... "block" the page up ...
</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>
+ <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">
- /*********************************************************************
+ <pre class="PROGRAMLISTING">/*********************************************************************
* This will stand out clearly in your code!
*********************************************************************/
if (this_variable == that_variable)
</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>
+ <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>
+ <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">
- /*********************************************************************
+ <pre class="PROGRAMLISTING">/*********************************************************************
* This will stand out clearly in your code,
* But the second example won't.
*********************************************************************/
</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>
+ <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>
+ <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>
+ <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>
<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>
+ <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>
</tr>
</table>
- <p><span class="emphasis"><i class="EMPHASIS">Instead
- of:</i></span></p>
+ <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>
+ <pre class="PROGRAMLISTING">int msiis5hack = 0; int msIis5Hack = 0;</pre>
</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>
+ <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>
+ <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>
+ <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)
+ <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" 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>
+ <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);
+ <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>
+ <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
+ <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>
</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>
+ <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};
+ <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">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>
</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><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>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>
</tr>
</table>
- <p><span class="emphasis"><i class="EMPHASIS">Instead
- of:</i></span></p>
+ <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span></p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<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>
+ <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>
</tr>
</table>
- <p><span class="emphasis"><i class="EMPHASIS">Instead
- of:</i></span></p>
+ <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>
+ <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>
</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>
+ <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>
</tr>
</table>
- <p><span class="emphasis"><i class="EMPHASIS">Instead
- of:</i></span></p>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
</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>
+ <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>
</tr>
</table>
- <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
- a_struct -> a_member; a_struct . a_member; function_name ();</p>
+ <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>
+ <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>
</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>
+ <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>
+ <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] =
+ <pre class="PROGRAMLISTING">static const char * const url_code_map[256] =
{
NULL, ...
};
<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>
+ <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>
</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>
+ <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>
<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>
+ <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>
</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>
+ <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>
+ <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 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">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>
</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>
+ <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>
+ <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>
+ <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
+ <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 */
+ <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>
+ <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. */
+ <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>
+ <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>
+ <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>
</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>
+ <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>
</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>
+ <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">
- /*********************************************************************
+ <pre class="PROGRAMLISTING">/*********************************************************************
* We're avoiding an include statement here!
*********************************************************************/
struct file_list;
</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>
+ <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>
+ <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>
+ <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="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>
+ <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>
</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>
+ <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>
+ <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>
+ <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>
+ <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>
</tr>
</table>
- <p><span class="emphasis"><i class="EMPHASIS">Instead
- of:</i></span></p>
+ <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>
+ <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>
+ <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
+ <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" 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>
+ <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">
- int load_re_filterfile(struct client_state *csp) { ... }
+ <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>
+ <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>
+ <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>
+ <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>/* 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>
+ <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>
+ <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$";
+ <pre class="PROGRAMLISTING">const char FILENAME_rcs[] = "$I<!-- Break CVS Substitution -->d$";
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
</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-version"
- 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>
+ <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> This declares the rcs variables that should be
+ added to the "show-version" 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>
</td>
</tr>
</table>
- <p><span class="emphasis"><i class="EMPHASIS">Example for function
- comments:</i></span></p>
+ <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">
- /*********************************************************************
+ <pre class="PROGRAMLISTING">/*********************************************************************
*
* Function : FUNCTION_NAME
*
</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>
+ <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">
+ <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>
+ <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="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>
<html>
<head>
<title>The CVS Repository</title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
+ <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="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=utf-8">
</head>
-<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
-"#840084" alink="#0000FF">
+<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">
+ <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="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>
+ <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>
+ <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>
+ <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="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>
+ <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="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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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"
+ <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="NAVFOOTER">
<hr align="left" width="100%">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
+ <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>
+ <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>
+ <td width="33%" align="right" valign="top">Documentation Guidelines</td>
</tr>
</table>
</div>
<html>
<head>
<title>Documentation Guidelines</title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
+ <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=utf-8">
</head>
-<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
-"#840084" alink="#0000FF">
+<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">
+ <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="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>
+ <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=
+ <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=
+ <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>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>
+ <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>
+ <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>
+ <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=
+ <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>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>
+ <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
+ <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>
+ <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
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>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>
+ "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" 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>
+ <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>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>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>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>
</para><br>
</itemizedlist><br>
</para><br>
- </p>This makes it easier
- to find the text amongst the tags ;-)
+ </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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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" 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>
+ <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>
+ <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>
+ <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.27"</span>.</td>
+ <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.27"</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=
+ <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>
+ <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>
+ <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
+ <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>
+ <p>There are others in various places that are defined for a specific purpose. Read the source!</p>
</div>
</div>
<div class="NAVFOOTER">
<hr align="left" width="100%">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
+ <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>
+ <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>
<html>
<head>
<title>Privoxy Developer Manual</title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
+ <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=utf-8">
</head>
-<body class="ARTICLE" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
-"#840084" alink="#0000FF">
+<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.84 2017/06/26
- 12:10:07 fabiankeil Exp $<br></p>
+ <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.83 2017/06/08 13:08:39 fabiankeil 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
+ <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.27. 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>
+ <p>Please note that this document is constantly evolving. This copy represents the state at the release of
+ version 3.0.27. 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>
</div>
<hr>
<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>
+ <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>
<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>
+ <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>
+ <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>
<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>
+ <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>
<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.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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <dt>4.8. <a href="coding.html#S46">Addendum: Template for files and function comment blocks:</a></dt>
</dl>
</dd>
<dt>5. <a href="testing.html">Testing Guidelines</a></dt>
<dd>
<dl>
- <dt>5.1. <a href="testing.html#TESTING-PLAN">Testplan for
- releases</a></dt>
+ <dt>5.1. <a href="testing.html#TESTING-PLAN">Testplan for releases</a></dt>
<dt>5.2. <a href="testing.html#FUZZING">Fuzzing Privoxy</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>
+ <dt>6.1. <a href="newrelease.html#VERSIONNUMBERS">Version numbers</a></dt>
+ <dt>6.2. <a href="newrelease.html#BEFORERELEASE">Before the Release: Freeze</a></dt>
+ <dt>6.3. <a href="newrelease.html#THERELEASE">Building and Releasing the Packages</a></dt>
<dd>
<dl>
- <dt>6.3.1. <a href="newrelease.html#PACK-GUIDELINES">Note on
- Privoxy Packaging</a></dt>
- <dt>6.3.2. <a href=
- "newrelease.html#NEWRELEASE-TARBALL">Source Tarball</a></dt>
- <dt>6.3.3. <a href="newrelease.html#NEWRELEASE-RPM">SuSE,
- Conectiva or Red Hat RPM</a></dt>
- <dt>6.3.4. <a href=
- "newrelease.html#NEWRELEASE-OS2">OS/2</a></dt>
- <dt>6.3.5. <a href=
- "newrelease.html#NEWRELEASE-SOLARIS">Solaris</a></dt>
- <dt>6.3.6. <a href=
- "newrelease.html#NEWRELEASE-WINDOWS">Windows</a></dt>
- <dt>6.3.7. <a href=
- "newrelease.html#NEWRELEASE-DEBIAN">Debian</a></dt>
- <dt>6.3.8. <a href="newrelease.html#NEWRELEASE-MACOSX">Mac OS
- X</a></dt>
- <dt>6.3.9. <a href=
- "newrelease.html#NEWRELEASE-FREEBSD">FreeBSD</a></dt>
+ <dt>6.3.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>
+ <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>
</div>
<div class="NAVFOOTER">
<hr align="left" width="100%">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
+ <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>
+ <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>
<html>
<head>
<title>Introduction</title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
+ <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=utf-8">
</head>
-<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
-"#840084" alink="#0000FF">
+<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">
+ <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="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>
+ <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>
+ <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>
+ <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>
</div>
<div class="NAVFOOTER">
<hr align="left" width="100%">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
+ <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>
+ <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="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>
<html>
<head>
<title>Releasing a New Version</title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
+ <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=utf-8">
</head>
-<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
-"#840084" alink="#0000FF">
+<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">
+ <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="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>
+ <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,
+ <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>
+ <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=
+ <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>
+ <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>
+ <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>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>
+ <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>
+ <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>
- and update the code status (CODE_STATUS="xxx") to one of "alpha",
- "beta" or "stable". Rebuild configure and GNUMakefile to make sure
- the updated values are being used.</p>
+ <p>Increment the version number (point from odd to even in development branches!) in <tt class=
+ "FILENAME">configure.in</tt> and update the code status (CODE_STATUS="xxx") to one of "alpha", "beta" or
+ "stable". Rebuild configure and GNUMakefile to make sure the updated values are being used.</p>
</li>
<li>
- <p>Use the dok-release target to update the sgml documentation
- source files.</p>
+ <p>Use the dok-release target to update the sgml documentation source files.</p>
</li>
<li>
- <p>If action file processing has changed and is not
- backward-compatible, make sure the "for-privoxy-version=x.y.z"
- minimum version number in default.action.master has been
- updated:</p>
+ <p>If action file processing has changed and is not backward-compatible, 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>
</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.
- README, 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>
+ <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.
+ README, 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>
+ <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
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
- <pre class="PROGRAMLISTING">
- mkdir dist # delete or choose different name if it already exists
+ <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>
- <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>
+ <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>
</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>
+ <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>
+ <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>
+ <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><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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <td><tt class="FILENAME">The User Manual</tt> (doc/webserver/user-manual/)</td>
</tr>
</tbody>
</table>
</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>
+ <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>
+ <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>
+ <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>
+ <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>
+ <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" 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>
+ <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>
</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>
+ <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>
+ <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>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
- <pre class="PROGRAMLISTING"> make <tt class=
- "REPLACEABLE"><i>dist</i></tt>-dist</pre>
+ <pre class="PROGRAMLISTING"> make <tt class="REPLACEABLE"><i>dist</i></tt>-dist</pre>
</td>
</tr>
</table>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
- <pre class="PROGRAMLISTING"> make <tt class=
- "REPLACEABLE"><i>dist</i></tt>-upload <tt class=
+ <pre class="PROGRAMLISTING"> make <tt class="REPLACEABLE"><i>dist</i></tt>-upload <tt class=
"REPLACEABLE"><i>rpm_packagerev</i></tt></pre>
</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>
+ <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>
+ <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>
</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>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>
+ <pre class="PROGRAMLISTING"> installExeName='privoxyos2_setup_X.Y.Z.exe'</pre>
</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>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>
+ <pre class="PROGRAMLISTING"> PACKAGEID="Privoxy Team\Privoxy\Privoxy Package\X\Y\Z"</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>
+ <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>
+ <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>
</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>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>
</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>
+ <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>
+ <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>
</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>
+ <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>
</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>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>
+ <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.27-UNRELEASED-1 "New upstream version"</pre>
+ <pre class="PROGRAMLISTING"> debchange -v 3.0.27-UNRELEASED-1 "New upstream version"</pre>
</td>
</tr>
</table>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
- <pre class="PROGRAMLISTING">
- dpkg-buildpackage -rfakeroot -us -uc -b</pre>
+ <pre class="PROGRAMLISTING"> dpkg-buildpackage -rfakeroot -us -uc -b</pre>
</td>
</tr>
</table>
- <p>This will create <tt class=
- "FILENAME">../privoxy_3.0.27-UNRELEASED-1_i386.deb</tt> which can be
- uploaded. To upload the package to Sourceforge, simply issue</p>
+ <p>This will create <tt class="FILENAME">../privoxy_3.0.27-UNRELEASED-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>
</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>
+ <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>
+ <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>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
</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>
+ <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" id=
- "OS-X-OSXSETUP-MODULE">6.3.8.2. osxsetup module
+ <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>
+ <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>
</td>
</tr>
</table>
- <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>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">
- zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg</pre>
+ <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
+ <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" id=
- "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>
+ <h4 class="SECT4"><a name="OS-X-MACSETUP-MODULE" id="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>
</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>
+ <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" 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>
+ <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="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>
+ <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>
+ <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>
+ <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.27 (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>
+ <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.27 (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" 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>
+ <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">
+ <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>
+ <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>
<html>
<head>
<title>Testing Guidelines</title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
+ <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=utf-8">
</head>
-<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
-"#840084" alink="#0000FF">
+<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">
+ <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="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>
+ <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>
+ <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>
+ <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>
+ <p>Remove any file that was left over. This includes (but is not limited to)</p>
<ul>
<li>
<p>/var/log/privoxy</p>
<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>
+ <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>
+ <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>
</ol>
</div>
<div class="SECT2">
- <h2 class="SECT2"><a name="FUZZING" id="FUZZING">5.2. Fuzzing
- Privoxy</a></h2>
- <p>To make fuzzing more convenient, Privoxy can be configured with
- --enable-fuzz which will result in the --fuzz option becoming
- available.</p>
+ <h2 class="SECT2"><a name="FUZZING" id="FUZZING">5.2. Fuzzing Privoxy</a></h2>
+ <p>To make fuzzing more convenient, Privoxy can be configured with --enable-fuzz which will result in the --fuzz
+ option becoming available.</p>
<p>Example (tested on ElectroBSD):</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
- <pre class="PROGRAMLISTING">
- # Compile Privoxy with instrumentation for afl
+ <pre class="PROGRAMLISTING"># Compile Privoxy with instrumentation for afl
$ export CC=afl-clang
$ export CFLAGS="-fsanitize=address -ggdb"
$ export CPPFLAGS=-I/usr/local/include/
</div>
<div class="NAVFOOTER">
<hr align="left" width="100%">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
+ <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>
+ <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>
+ <td width="33%" align="right" valign="top">Releasing a New Version</td>
</tr>
</table>
</div>
<html>
<head>
<title>Update the Webserver</title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
+ <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="Releasing a New Version" href=
- "newrelease.html">
+ <link rel="PREVIOUS" 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=utf-8">
</head>
-<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
-"#840084" alink="#0000FF">
+<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">
+ <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=
- "newrelease.html" accesskey="P">Prev</a></td>
+ <td width="10%" align="left" valign="bottom"><a href="newrelease.html" accesskey="P">Prev</a></td>
<td width="80%" align="center" valign="bottom"></td>
<td width="10%" align="right" valign="bottom"> </td>
</tr>
<hr align="left" width="100%">
</div>
<div class="SECT1">
- <h1 class="SECT1"><a name="WEBSERVER-UPDATE" id="WEBSERVER-UPDATE">7.
- Update the Webserver</a></h1>
- <p>The webserver should be updated at least with each stable release.
- When updating, please follow these steps to make sure that no broken
- links, inconsistent contents or permission problems will occur (as it has
- many times in the past!):</p>
- <p>If you have changed anything in the stable-branch documentation source
- SGML files, do:</p>
+ <h1 class="SECT1"><a name="WEBSERVER-UPDATE" id="WEBSERVER-UPDATE">7. Update the Webserver</a></h1>
+ <p>The webserver should be updated at least with each stable release. When updating, please follow these steps to
+ make sure that no broken links, inconsistent contents or permission problems will occur (as it has many times in
+ the past!):</p>
+ <p>If you have changed anything in the stable-branch documentation source SGML files, do:</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
</td>
</tr>
</table>
- <p>That will generate <tt class=
- "FILENAME">doc/webserver/user-manual</tt>, <tt class=
- "FILENAME">doc/webserver/developer-manual</tt>, <tt class=
- "FILENAME">doc/webserver/faq</tt>, <tt class=
+ <p>That will generate <tt class="FILENAME">doc/webserver/user-manual</tt>, <tt class=
+ "FILENAME">doc/webserver/developer-manual</tt>, <tt class="FILENAME">doc/webserver/faq</tt>, <tt class=
"FILENAME">doc/webserver/index.html</tt> automatically.</p>
<p>If you changed the manual page sources, generate <tt class=
- "FILENAME">doc/webserver/man-page/privoxy-man-page.html</tt> by running
- <span class="QUOTE">"<b class="COMMAND">make man</b>"</span>. (This is a
- separate target due to dependencies on some obscure perl scripts [now in
- CVS, but not well tested]. See comments in <tt class=
- "FILENAME">GNUmakefile</tt>.)</p>
- <p>If you want to add new files to the webserver, create them locally in
- the <tt class="FILENAME">doc/webserver/*</tt> directory (or create new
- directories under <tt class="FILENAME">doc/webserver</tt>).</p>
- <p>Next, commit any changes from the above steps to CVS. All set? If
- these are docs in the stable branch, then do:</p>
+ "FILENAME">doc/webserver/man-page/privoxy-man-page.html</tt> by running <span class="QUOTE">"<b class=
+ "COMMAND">make man</b>"</span>. (This is a separate target due to dependencies on some obscure perl scripts [now in
+ CVS, but not well tested]. See comments in <tt class="FILENAME">GNUmakefile</tt>.)</p>
+ <p>If you want to add new files to the webserver, create them locally in the <tt class=
+ "FILENAME">doc/webserver/*</tt> directory (or create new directories under <tt class=
+ "FILENAME">doc/webserver</tt>).</p>
+ <p>Next, commit any changes from the above steps to CVS. All set? If these are docs in the stable branch, then
+ do:</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
</td>
</tr>
</table>
- <p>This will do the upload to <a href="https://www.privoxy.org/" target=
- "_top">the webserver</a> (www.privoxy.org) and ensure all files and
- directories there are group writable.</p>
- <p>Please do <span class="emphasis"><i class="EMPHASIS">NOT</i></span>
- use any other means of transferring files to the webserver to avoid
- permission problems. Also, please do not upload docs from development
- branches or versions. The publicly posted docs should be in sync with the
- last official release.</p>
+ <p>This will do the upload to <a href="https://www.privoxy.org/" target="_top">the webserver</a> (www.privoxy.org)
+ and ensure all files and directories there are group writable.</p>
+ <p>Please do <span class="emphasis"><i class="EMPHASIS">NOT</i></span> use any other means of transferring files to
+ the webserver to avoid permission problems. Also, please do not upload docs from development branches or versions.
+ The publicly posted docs should be in sync with the last official release.</p>
</div>
<div class="NAVFOOTER">
<hr align="left" width="100%">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
+ <table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
- <td width="33%" align="left" valign="top"><a href="newrelease.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="left" valign="top"><a href="newrelease.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"> </td>
</tr>
<tr>
- <td width="33%" align="left" valign="top">Releasing a New
- Version</td>
+ <td width="33%" align="left" valign="top">Releasing a New Version</td>
<td width="34%" align="center" valign="top"> </td>
<td width="33%" align="right" valign="top"> </td>
</tr>
<html>
<head>
<title>Configuration</title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
- <link rel="HOME" title="Privoxy Frequently Asked Questions" href=
- "index.html">
+ <meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
+ <link rel="HOME" title="Privoxy Frequently Asked Questions" href="index.html">
<link rel="PREVIOUS" title="Installation" href="installation.html">
<link rel="NEXT" title="Miscellaneous" href="misc.html">
<link rel="STYLESHEET" type="text/css" href="../p_doc.css">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
-<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
-"#840084" alink="#0000FF">
+<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">
+ <table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
- <th colspan="3" align="center">Privoxy Frequently Asked
- Questions</th>
+ <th colspan="3" align="center">Privoxy Frequently Asked Questions</th>
</tr>
<tr>
- <td width="10%" align="left" valign="bottom"><a href=
- "installation.html" accesskey="P">Prev</a></td>
+ <td width="10%" align="left" valign="bottom"><a href="installation.html" accesskey="P">Prev</a></td>
<td width="80%" align="center" valign="bottom"></td>
- <td width="10%" align="right" valign="bottom"><a href="misc.html"
- accesskey="N">Next</a></td>
+ <td width="10%" align="right" valign="bottom"><a href="misc.html" accesskey="N">Next</a></td>
</tr>
</table>
<hr align="left" width="100%">
</div>
<div class="SECT1">
- <h1 class="SECT1"><a name="CONFIGURATION" id="CONFIGURATION">3.
- Configuration</a></h1>
+ <h1 class="SECT1"><a name="CONFIGURATION" id="CONFIGURATION">3. Configuration</a></h1>
<div class="SECT2">
- <h3 class="SECT2"><a name="ACTIONSFILE" id="ACTIONSFILE">3.1. What
- exactly is an <span class="QUOTE">"actions"</span> file?</a></h3>
- <p><span class="APPLICATION">Privoxy</span> utilizes the concept of
- <span class="QUOTE">" <a href=
- "../user-manual/actions-file.html#ACTIONS" target=
- "_top">actions</a>"</span> that are used to manipulate and control web
- page data. <a href="../user-manual/actions-file.html" target=
- "_top">Actions files</a> are where these <a href=
- "../user-manual/actions-file.html#ACTIONS" target="_top">actions</a>
- that <span class="APPLICATION">Privoxy</span> could take while
- processing a certain request, are configured. Typically, you would
- define a set of default actions that apply globally to all URLs, then
- add exceptions to these defaults where needed. There is a wide array of
- actions available that give the user a high degree of control and
- flexibility on how to process each and every web page.</p>
- <p>Actions can be defined on a <a href=
- "../user-manual/actions-file.html#AF-PATTERNS" target="_top">URL
- pattern</a> basis, i.e. for single URLs, whole web sites, groups or
- parts thereof etc. Actions can also be grouped together and then
- applied to requests matching one or more patterns. There are many
- possible actions that might apply to any given site. As an example, if
- you are blocking <a href="http://en.wikipedia.org/wiki/Browser_cookie"
- target="_top">cookies</a> as one of your default actions, but need to
- accept cookies from a given site, you would need to define an exception
- for this site in one of your actions files, preferably in <tt class=
- "FILENAME">user.action</tt>.</p>
+ <h3 class="SECT2"><a name="ACTIONSFILE" id="ACTIONSFILE">3.1. What exactly is an <span class=
+ "QUOTE">"actions"</span> file?</a></h3>
+ <p><span class="APPLICATION">Privoxy</span> utilizes the concept of <span class="QUOTE">" <a href=
+ "../user-manual/actions-file.html#ACTIONS" target="_top">actions</a>"</span> that are used to manipulate and
+ control web page data. <a href="../user-manual/actions-file.html" target="_top">Actions files</a> are where these
+ <a href="../user-manual/actions-file.html#ACTIONS" target="_top">actions</a> that <span class=
+ "APPLICATION">Privoxy</span> could take while processing a certain request, are configured. Typically, you would
+ define a set of default actions that apply globally to all URLs, then add exceptions to these defaults where
+ needed. There is a wide array of actions available that give the user a high degree of control and flexibility on
+ how to process each and every web page.</p>
+ <p>Actions can be defined on a <a href="../user-manual/actions-file.html#AF-PATTERNS" target="_top">URL
+ pattern</a> basis, i.e. for single URLs, whole web sites, groups or parts thereof etc. Actions can also be
+ grouped together and then applied to requests matching one or more patterns. There are many possible actions that
+ might apply to any given site. As an example, if you are blocking <a href=
+ "http://en.wikipedia.org/wiki/Browser_cookie" target="_top">cookies</a> as one of your default actions, but need
+ to accept cookies from a given site, you would need to define an exception for this site in one of your actions
+ files, preferably in <tt class="FILENAME">user.action</tt>.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="ACTIONSS" id="ACTIONSS">3.2. The
- <span class="QUOTE">"actions"</span> concept confuses me. Please list
- some of these <span class="QUOTE">"actions"</span>.</a></h3>
- <p>For a comprehensive discussion of the actions concept, please refer
- to the <a href="../user-manual/actions-file.html" target="_top">actions
- file chapter</a> in the <a href="../user-manual/index.html" target=
- "_top">User Manual</a>. It includes a <a href=
- "../user-manual/actions-file.html#ACTIONS" target="_top">list of all
- actions</a> and an <a href=
- "../user-manual/actions-file.html#ACT-EXAMPLES" target="_top">actions
- file tutorial</a> to get you started.</p>
+ <h3 class="SECT2"><a name="ACTIONSS" id="ACTIONSS">3.2. The <span class="QUOTE">"actions"</span> concept confuses
+ me. Please list some of these <span class="QUOTE">"actions"</span>.</a></h3>
+ <p>For a comprehensive discussion of the actions concept, please refer to the <a href=
+ "../user-manual/actions-file.html" target="_top">actions file chapter</a> in the <a href=
+ "../user-manual/index.html" target="_top">User Manual</a>. It includes a <a href=
+ "../user-manual/actions-file.html#ACTIONS" target="_top">list of all actions</a> and an <a href=
+ "../user-manual/actions-file.html#ACT-EXAMPLES" target="_top">actions file tutorial</a> to get you started.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="ACTCONFIG" id="ACTCONFIG">3.3. How are
- actions files configured? What is the easiest way to do this?</a></h3>
- <p>Actions files are just text files in a special syntax and can be
- edited with a text editor. But probably the easiest way is to access
- <span class="APPLICATION">Privoxy</span>'s user interface with your web
- browser at <a href="http://config.privoxy.org/" target=
- "_top">http://config.privoxy.org/</a> (Shortcut: <a href="http://p.p/"
- target="_top">http://p.p/</a>) and then select <span class=
- "QUOTE">"<a href="http://config.privoxy.org/show-status" target=
- "_top">View & change the current configuration</a>"</span> from the
- menu. Note that this feature must be explicitly enabled in the main
- config file (see <a href=
- "../user-manual/config.html#ENABLE-EDIT-ACTIONS" target=
- "_top">enable-edit-actions</a>).</p>
+ <h3 class="SECT2"><a name="ACTCONFIG" id="ACTCONFIG">3.3. How are actions files configured? What is the easiest
+ way to do this?</a></h3>
+ <p>Actions files are just text files in a special syntax and can be edited with a text editor. But probably the
+ easiest way is to access <span class="APPLICATION">Privoxy</span>'s user interface with your web browser at
+ <a href="http://config.privoxy.org/" target="_top">http://config.privoxy.org/</a> (Shortcut: <a href=
+ "http://p.p/" target="_top">http://p.p/</a>) and then select <span class="QUOTE">"<a href=
+ "http://config.privoxy.org/show-status" target="_top">View & change the current configuration</a>"</span>
+ from the menu. Note that this feature must be explicitly enabled in the main config file (see <a href=
+ "../user-manual/config.html#ENABLE-EDIT-ACTIONS" target="_top">enable-edit-actions</a>).</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="AEN420" id="AEN420">3.4. There are several
- different <span class="QUOTE">"actions"</span> files. What are the
- differences?</a></h3>
- <p>Please have a look at the <a href="../user-manual/actions-file.html"
- target="_top">the actions chapter</a> in the <a href=
- "../user-manual/index.html" target="_top">User Manual</a> for a
- detailed explanation.</p>
+ <h3 class="SECT2"><a name="AEN420" id="AEN420">3.4. There are several different <span class=
+ "QUOTE">"actions"</span> files. What are the differences?</a></h3>
+ <p>Please have a look at the <a href="../user-manual/actions-file.html" target="_top">the actions chapter</a> in
+ the <a href="../user-manual/index.html" target="_top">User Manual</a> for a detailed explanation.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="GETUPDATES" id="GETUPDATES">3.5. Where can I
- get updated Actions Files?</a></h3>
- <p>Based on your feedback and the continuing development, updates of
- <tt class="FILENAME">default.action</tt> will be made available from
- time to time on the <a href=
- "https://sourceforge.net/project/showfiles.php?group_id=11118" target=
- "_top">files section</a> of our <a href=
- "https://sourceforge.net/projects/ijbswa/" target="_top">project
- page</a>.</p>
- <p>If you wish to receive an email notification whenever we release
- updates of <span class="APPLICATION">Privoxy</span> or the actions
- file, <a href=
- "https://lists.privoxy.org/mailman/listinfo/privoxy-announce" target=
- "_top">subscribe to our announce mailing list</a>,
- privoxy-announce@lists.privoxy.org.</p>
+ <h3 class="SECT2"><a name="GETUPDATES" id="GETUPDATES">3.5. Where can I get updated Actions Files?</a></h3>
+ <p>Based on your feedback and the continuing development, updates of <tt class="FILENAME">default.action</tt>
+ will be made available from time to time on the <a href=
+ "https://sourceforge.net/project/showfiles.php?group_id=11118" target="_top">files section</a> of our <a href=
+ "https://sourceforge.net/projects/ijbswa/" target="_top">project page</a>.</p>
+ <p>If you wish to receive an email notification whenever we release updates of <span class=
+ "APPLICATION">Privoxy</span> or the actions file, <a href=
+ "https://lists.privoxy.org/mailman/listinfo/privoxy-announce" target="_top">subscribe to our announce mailing
+ list</a>, privoxy-announce@lists.privoxy.org.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="NEWCONFIG" id="NEWCONFIG">3.6. Can I use my
- old config files?</a></h3>
- <p>The syntax and purpose of configuration files has remained roughly
- the same throughout the 3.x series, but backwards compatibility is not
- guaranteed. Also each release contains updated, <span class=
- "QUOTE">"improved"</span> versions and it is therefore strongly
- recommended to install the newer configuration files and merge back
- your modifications.</p>
+ <h3 class="SECT2"><a name="NEWCONFIG" id="NEWCONFIG">3.6. Can I use my old config files?</a></h3>
+ <p>The syntax and purpose of configuration files has remained roughly the same throughout the 3.x series, but
+ backwards compatibility is not guaranteed. Also each release contains updated, <span class=
+ "QUOTE">"improved"</span> versions and it is therefore strongly recommended to install the newer configuration
+ files and merge back your modifications.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="DIFFICULT" id="DIFFICULT">3.7. Why is the
- configuration so complicated?</a></h3>
- <p><span class="QUOTE">"Complicated"</span> is in the eye of the
- beholder.</p>
- <p>Privoxy is currently mainly written by and for people who are
- already familiar with the underlying concepts like regular expressions,
- HTTP and HTML, or are willing to become familiar with them to be able
- to get the most out of a powerful and flexible tool such as
- Privoxy.</p>
- <p>While everybody is expected to be able to get a Privoxy default
- installation up and running, fine-tuning requires a certain amount of
- background information and Privoxy's documentation mainly concentrates
- on the Privoxy-specific parts while only providing references to the
- rest.</p>
- <p>If you or anyone you know has the skills, time and energy to reduce
- the barrier of entry, please <a href="general.html#PARTICIPATE">get
- involved</a>.</p>
+ <h3 class="SECT2"><a name="DIFFICULT" id="DIFFICULT">3.7. Why is the configuration so complicated?</a></h3>
+ <p><span class="QUOTE">"Complicated"</span> is in the eye of the beholder.</p>
+ <p>Privoxy is currently mainly written by and for people who are already familiar with the underlying concepts
+ like regular expressions, HTTP and HTML, or are willing to become familiar with them to be able to get the most
+ out of a powerful and flexible tool such as Privoxy.</p>
+ <p>While everybody is expected to be able to get a Privoxy default installation up and running, fine-tuning
+ requires a certain amount of background information and Privoxy's documentation mainly concentrates on the
+ Privoxy-specific parts while only providing references to the rest.</p>
+ <p>If you or anyone you know has the skills, time and energy to reduce the barrier of entry, please <a href=
+ "general.html#PARTICIPATE">get involved</a>.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="YAHOO" id="YAHOO">3.8. How can I make my
- Yahoo/Hotmail/Gmail account work?</a></h3>
- <p>The default configuration shouldn't impact the usability of any of
- these services. It may, however, make all <a href=
- "http://en.wikipedia.org/wiki/Browser_cookie" target="_top">cookies</a>
- temporary, so that your browser will forget your login credentials in
- between browser sessions. If you would like not to have to log in
- manually each time you access those websites, simply turn off all
- cookie handling for them in the <tt class="FILENAME">user.action</tt>
- file. An example for yahoo might look like:</p>
+ <h3 class="SECT2"><a name="YAHOO" id="YAHOO">3.8. How can I make my Yahoo/Hotmail/Gmail account work?</a></h3>
+ <p>The default configuration shouldn't impact the usability of any of these services. It may, however, make all
+ <a href="http://en.wikipedia.org/wiki/Browser_cookie" target="_top">cookies</a> temporary, so that your browser
+ will forget your login credentials in between browser sessions. If you would like not to have to log in manually
+ each time you access those websites, simply turn off all cookie handling for them in the <tt class=
+ "FILENAME">user.action</tt> file. An example for yahoo might look like:</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="SCREEN"># Allow all cookies for Yahoo login:
#
{ -<a href="../user-manual/actions-file.html#CRUNCH-INCOMING-COOKIES" target=
-"_top">crunch-incoming-cookies</a> -<a href=
-"../user-manual/actions-file.html#CRUNCH-OUTGOING-COOKIES" target=
-"_top">crunch-outgoing-cookies</a> -<a href=
-"../user-manual/actions-file.html#SESSION-COOKIES-ONLY" target=
+"_top">crunch-incoming-cookies</a> -<a href="../user-manual/actions-file.html#CRUNCH-OUTGOING-COOKIES" target=
+"_top">crunch-outgoing-cookies</a> -<a href="../user-manual/actions-file.html#SESSION-COOKIES-ONLY" target=
"_top">session-cookies-only</a> }
.login.yahoo.com</pre>
</td>
</tr>
</table>
- <p>These kinds of sites are often quite complex and heavy with <a href=
- "http://en.wikipedia.org/wiki/Javascript" target="_top">Javascript</a>
- and thus <span class="QUOTE">"fragile"</span>. So if <span class=
- "emphasis"><i class="EMPHASIS">still</i></span> a problem, we have an
- <a href="../user-manual/actions-file.html#ALIASES" target=
- "_top">alias</a> just for such sticky situations:</p>
+ <p>These kinds of sites are often quite complex and heavy with <a href="http://en.wikipedia.org/wiki/Javascript"
+ target="_top">Javascript</a> and thus <span class="QUOTE">"fragile"</span>. So if <span class=
+ "emphasis"><i class="EMPHASIS">still</i></span> a problem, we have an <a href=
+ "../user-manual/actions-file.html#ALIASES" target="_top">alias</a> just for such sticky situations:</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
</td>
</tr>
</table>
- <p>Be sure to flush your browser's caches whenever making these kinds
- of changes, just to make sure the changes <span class=
- "QUOTE">"take"</span>.</p>
- <p>Make sure the domain, host and path are appropriate as well. Your
- browser can tell you where you are specifically and you should use that
- information for your configuration settings. Note that above it is not
- referenced as <tt class="LITERAL">gmail.com</tt>, which is a valid
- domain name.</p>
+ <p>Be sure to flush your browser's caches whenever making these kinds of changes, just to make sure the changes
+ <span class="QUOTE">"take"</span>.</p>
+ <p>Make sure the domain, host and path are appropriate as well. Your browser can tell you where you are
+ specifically and you should use that information for your configuration settings. Note that above it is not
+ referenced as <tt class="LITERAL">gmail.com</tt>, which is a valid domain name.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="CONFIGFILES" id="CONFIGFILES">3.9. What's
- the difference between the <span class="QUOTE">"Cautious"</span>,
- <span class="QUOTE">"Medium"</span> and <span class=
- "QUOTE">"Advanced"</span> defaults?</a></h3>
- <p>Configuring <span class="APPLICATION">Privoxy</span> is not entirely
- trivial. To help you get started, we provide you with three different
- default action <span class="QUOTE">"profiles"</span> in the web based
- actions file editor at <a href="http://config.privoxy.org/show-status"
- target="_top">http://config.privoxy.org/show-status</a>. See the
- <a href="../user-manual/actions-file.html" target="_top"><i class=
- "CITETITLE">User Manual</i></a> for a list of actions, and how the
- default profiles are set.</p>
- <p>Where the defaults are likely to break some sites, exceptions for
- known popular <span class="QUOTE">"problem"</span> sites are included,
- but in general, the more aggressive your default settings are, the more
- exceptions you will have to make later. New users are best to start off
- in <span class="QUOTE">"Cautious"</span> setting. This is safest and
- will have the fewest problems. See the <a href=
- "../user-manual/index.html" target="_top"><i class="CITETITLE">User
- Manual</i></a> for a more detailed discussion.</p>
- <p>It should be noted that the <span class="QUOTE">"Advanced"</span>
- profile (formerly known as the <span class=
- "QUOTE">"Adventuresome"</span> profile) is more aggressive, and will
- make use of some of <span class="APPLICATION">Privoxy's</span> advanced
- features. Use at your own risk!</p>
+ <h3 class="SECT2"><a name="CONFIGFILES" id="CONFIGFILES">3.9. What's the difference between the <span class=
+ "QUOTE">"Cautious"</span>, <span class="QUOTE">"Medium"</span> and <span class="QUOTE">"Advanced"</span>
+ defaults?</a></h3>
+ <p>Configuring <span class="APPLICATION">Privoxy</span> is not entirely trivial. To help you get started, we
+ provide you with three different default action <span class="QUOTE">"profiles"</span> in the web based actions
+ file editor at <a href="http://config.privoxy.org/show-status" target=
+ "_top">http://config.privoxy.org/show-status</a>. See the <a href="../user-manual/actions-file.html" target=
+ "_top"><i class="CITETITLE">User Manual</i></a> for a list of actions, and how the default profiles are set.</p>
+ <p>Where the defaults are likely to break some sites, exceptions for known popular <span class=
+ "QUOTE">"problem"</span> sites are included, but in general, the more aggressive your default settings are, the
+ more exceptions you will have to make later. New users are best to start off in <span class=
+ "QUOTE">"Cautious"</span> setting. This is safest and will have the fewest problems. See the <a href=
+ "../user-manual/index.html" target="_top"><i class="CITETITLE">User Manual</i></a> for a more detailed
+ discussion.</p>
+ <p>It should be noted that the <span class="QUOTE">"Advanced"</span> profile (formerly known as the <span class=
+ "QUOTE">"Adventuresome"</span> profile) is more aggressive, and will make use of some of <span class=
+ "APPLICATION">Privoxy's</span> advanced features. Use at your own risk!</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="BROWSECONFIG" id="BROWSECONFIG">3.10. Why
- can I change the configuration with a browser? Does that not raise
- security issues?</a></h3>
- <p>It may seem strange that regular users can edit the config files
- with their browsers, although the whole <tt class=
- "FILENAME">/etc/privoxy</tt> hierarchy belongs to the user <span class=
- "QUOTE">"privoxy"</span>, with only 644 permissions.</p>
- <p>When you use the browser-based editor, <span class=
- "APPLICATION">Privoxy</span> itself is writing to the config files.
- Because <span class="APPLICATION">Privoxy</span> is running as the user
- <span class="QUOTE">"privoxy"</span>, it can update its own config
- files.</p>
- <p>If you run <span class="APPLICATION">Privoxy</span> for multiple
- untrusted users (e.g. in a LAN) or aren't entirely in control of your
- own browser, you will probably want to make sure that the web-based
- editor and remote toggle features are <span class="QUOTE">"off"</span>
- by setting <span class="QUOTE">"<tt class="LITERAL"><a href=
- "../user-manual/config.html#ENABLE-EDIT-ACTIONS" target=
- "_top">enable-edit-actions</a> 0</tt>"</span> and <span class=
- "QUOTE">"<tt class="LITERAL"><a href=
- "../user-manual/config.html#ENABLE-REMOTE-TOGGLE" target=
- "_top">enable-remote-toggle</a> 0</tt>"</span> in the <a href=
- "../user-manual/config.html" target="_top">main configuration
- file</a>.</p>
- <p>As of <span class="APPLICATION">Privoxy</span> 3.0.7 these options
- are disabled by default.</p>
+ <h3 class="SECT2"><a name="BROWSECONFIG" id="BROWSECONFIG">3.10. Why can I change the configuration with a
+ browser? Does that not raise security issues?</a></h3>
+ <p>It may seem strange that regular users can edit the config files with their browsers, although the whole
+ <tt class="FILENAME">/etc/privoxy</tt> hierarchy belongs to the user <span class="QUOTE">"privoxy"</span>, with
+ only 644 permissions.</p>
+ <p>When you use the browser-based editor, <span class="APPLICATION">Privoxy</span> itself is writing to the
+ config files. Because <span class="APPLICATION">Privoxy</span> is running as the user <span class=
+ "QUOTE">"privoxy"</span>, it can update its own config files.</p>
+ <p>If you run <span class="APPLICATION">Privoxy</span> for multiple untrusted users (e.g. in a LAN) or aren't
+ entirely in control of your own browser, you will probably want to make sure that the web-based editor and remote
+ toggle features are <span class="QUOTE">"off"</span> by setting <span class="QUOTE">"<tt class="LITERAL"><a href=
+ "../user-manual/config.html#ENABLE-EDIT-ACTIONS" target="_top">enable-edit-actions</a> 0</tt>"</span> and
+ <span class="QUOTE">"<tt class="LITERAL"><a href="../user-manual/config.html#ENABLE-REMOTE-TOGGLE" target=
+ "_top">enable-remote-toggle</a> 0</tt>"</span> in the <a href="../user-manual/config.html" target="_top">main
+ configuration file</a>.</p>
+ <p>As of <span class="APPLICATION">Privoxy</span> 3.0.7 these options are disabled by default.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="FILTERFILE" id="FILTERFILE">3.11. What is
- the <tt class="FILENAME">default.filter</tt> file? What is a
- <span class="QUOTE">"filter"</span>?</a></h3>
- <p>The <a href="../user-manual/filter-file.html" target=
- "_top"><tt class="FILENAME">default.filter</tt></a> file is where
- <span class="emphasis"><i class="EMPHASIS">filters</i></span> as
- supplied by the developers are defined. Filters are a special subset of
- actions that can be used to modify or remove web page content or
- headers on the fly. Content filters can be applied to <span class=
- "emphasis"><i class="EMPHASIS">anything</i></span> in the page source,
- header filters can be applied to either server or client headers.
- Regular expressions are used to accomplish this.</p>
- <p>There are a number of pre-defined filters to deal with common
- annoyances. The filters are only defined here, to invoke them, you need
- to use the <a href="../user-manual/actions-file.html#FILTER" target=
- "_top"><tt class="LITERAL">filter</tt> action</a> in one of the actions
- files. Content filtering is automatically disabled for inappropriate
- MIME types, but if you know better than Privoxy what should or should
- not be filtered you can filter any content you like.</p>
- <p>Filters should <span class="emphasis"><i class=
- "EMPHASIS">not</i></span> be confused with <a href=
- "../user-manual/actions-file.html#BLOCK" target="_top"><tt class=
- "LITERAL">blocks</tt></a>, which is a completely different action, and
- is more typically used to block ads and unwanted sites.</p>
- <p>If you are familiar with regular expressions, and HTML, you can look
- at the provided <tt class="FILENAME">default.filter</tt> with a text
- editor and define your own filters. This is potentially a very powerful
- feature, but requires some expertise in both regular expressions and
- HTML/HTTP. You should place any modifications to the default filters,
- or any new ones you create in a separate file, such as <tt class=
- "FILENAME">user.filter</tt>, so they won't be overwritten during
- upgrades. The ability to define multiple filter files in <tt class=
- "FILENAME">config</tt> is a new feature as of v. 3.0.5.</p>
- <p>There is no GUI editor option for this part of the configuration,
- but you can disable/enable the various pre-defined filters of the
- included <tt class="FILENAME">default.filter</tt> file with the
- <a href="http://config.privoxy.org/show-status" target="_top">web-based
- actions file editor</a>. Note that the custom actions editor must be
- explicitly enabled in the main config file (see <a href=
- "../user-manual/config.html#ENABLE-EDIT-ACTIONS" target=
- "_top">enable-edit-actions</a>).</p>
- <p>If you intend to develop your own filters, you might want to have a
- look at <a href="https://www.fabiankeil.de/sourcecode/pft/" target=
- "_top">Privoxy-Filter-Test</a>.</p>
+ <h3 class="SECT2"><a name="FILTERFILE" id="FILTERFILE">3.11. What is the <tt class="FILENAME">default.filter</tt>
+ file? What is a <span class="QUOTE">"filter"</span>?</a></h3>
+ <p>The <a href="../user-manual/filter-file.html" target="_top"><tt class="FILENAME">default.filter</tt></a> file
+ is where <span class="emphasis"><i class="EMPHASIS">filters</i></span> as supplied by the developers are defined.
+ Filters are a special subset of actions that can be used to modify or remove web page content or headers on the
+ fly. Content filters can be applied to <span class="emphasis"><i class="EMPHASIS">anything</i></span> in the page
+ source, header filters can be applied to either server or client headers. Regular expressions are used to
+ accomplish this.</p>
+ <p>There are a number of pre-defined filters to deal with common annoyances. The filters are only defined here,
+ to invoke them, you need to use the <a href="../user-manual/actions-file.html#FILTER" target="_top"><tt class=
+ "LITERAL">filter</tt> action</a> in one of the actions files. Content filtering is automatically disabled for
+ inappropriate MIME types, but if you know better than Privoxy what should or should not be filtered you can
+ filter any content you like.</p>
+ <p>Filters should <span class="emphasis"><i class="EMPHASIS">not</i></span> be confused with <a href=
+ "../user-manual/actions-file.html#BLOCK" target="_top"><tt class="LITERAL">blocks</tt></a>, which is a completely
+ different action, and is more typically used to block ads and unwanted sites.</p>
+ <p>If you are familiar with regular expressions, and HTML, you can look at the provided <tt class=
+ "FILENAME">default.filter</tt> with a text editor and define your own filters. This is potentially a very
+ powerful feature, but requires some expertise in both regular expressions and HTML/HTTP. You should place any
+ modifications to the default filters, or any new ones you create in a separate file, such as <tt class=
+ "FILENAME">user.filter</tt>, so they won't be overwritten during upgrades. The ability to define multiple filter
+ files in <tt class="FILENAME">config</tt> is a new feature as of v. 3.0.5.</p>
+ <p>There is no GUI editor option for this part of the configuration, but you can disable/enable the various
+ pre-defined filters of the included <tt class="FILENAME">default.filter</tt> file with the <a href=
+ "http://config.privoxy.org/show-status" target="_top">web-based actions file editor</a>. Note that the custom
+ actions editor must be explicitly enabled in the main config file (see <a href=
+ "../user-manual/config.html#ENABLE-EDIT-ACTIONS" target="_top">enable-edit-actions</a>).</p>
+ <p>If you intend to develop your own filters, you might want to have a look at <a href=
+ "https://www.fabiankeil.de/sourcecode/pft/" target="_top">Privoxy-Filter-Test</a>.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="LANCONFIG" id="LANCONFIG">3.12. How can I
- set up Privoxy to act as a proxy for my LAN?</a></h3>
- <p>By default, <span class="APPLICATION">Privoxy</span> only responds
- to requests from <tt class="LITERAL">127.0.0.1</tt> (localhost). To
- have it act as a server for a network, this needs to be changed in the
- <a href="../user-manual/config.html" target="_top">main configuration
- file</a>. Look for the <tt class="LITERAL"><a href=
- "../user-manual/config.html#LISTEN-ADDRESS" target=
- "_top">listen-address</a></tt> option, which may be commented out with
- a <span class="QUOTE">"#"</span> symbol. Make sure it is uncommented,
- and assign it the address of the LAN gateway interface, and port number
- to use. Assuming your LAN address is 192.168.1.1 and you wish to run
- <span class="APPLICATION">Privoxy</span> on port 8118, this line should
- look like:</p>
+ <h3 class="SECT2"><a name="LANCONFIG" id="LANCONFIG">3.12. How can I set up Privoxy to act as a proxy for my
+ LAN?</a></h3>
+ <p>By default, <span class="APPLICATION">Privoxy</span> only responds to requests from <tt class=
+ "LITERAL">127.0.0.1</tt> (localhost). To have it act as a server for a network, this needs to be changed in the
+ <a href="../user-manual/config.html" target="_top">main configuration file</a>. Look for the <tt class=
+ "LITERAL"><a href="../user-manual/config.html#LISTEN-ADDRESS" target="_top">listen-address</a></tt> option, which
+ may be commented out with a <span class="QUOTE">"#"</span> symbol. Make sure it is uncommented, and assign it the
+ address of the LAN gateway interface, and port number to use. Assuming your LAN address is 192.168.1.1 and you
+ wish to run <span class="APPLICATION">Privoxy</span> on port 8118, this line should look like:</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
</td>
</tr>
</table>
- <p>Save the file, and restart <span class="APPLICATION">Privoxy</span>.
- Configure all browsers on the network then to use this address and port
- number.</p>
- <p>Alternately, you can have <span class="APPLICATION">Privoxy</span>
- listen on all available interfaces:</p>
+ <p>Save the file, and restart <span class="APPLICATION">Privoxy</span>. Configure all browsers on the network
+ then to use this address and port number.</p>
+ <p>Alternately, you can have <span class="APPLICATION">Privoxy</span> listen on all available interfaces:</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
</td>
</tr>
</table>
- <p>And then use <span class="APPLICATION">Privoxy's</span> <a href=
- "../user-manual/config.html#PERMIT-ACCESS" target=
- "_top">permit-access</a> feature to limit connections. A firewall in
- this situation is recommended as well.</p>
- <p>The above steps should be the same for any TCP network, regardless
- of operating system.</p>
- <p>If you run <span class="APPLICATION">Privoxy</span> on a LAN with
- untrusted users, we recommend that you double-check the <a href=
- "../user-manual/config.html#ACCESS-CONTROL" target="_top">access
- control and security</a> options!</p>
+ <p>And then use <span class="APPLICATION">Privoxy's</span> <a href="../user-manual/config.html#PERMIT-ACCESS"
+ target="_top">permit-access</a> feature to limit connections. A firewall in this situation is recommended as
+ well.</p>
+ <p>The above steps should be the same for any TCP network, regardless of operating system.</p>
+ <p>If you run <span class="APPLICATION">Privoxy</span> on a LAN with untrusted users, we recommend that you
+ double-check the <a href="../user-manual/config.html#ACCESS-CONTROL" target="_top">access control and
+ security</a> options!</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="NOSEEUM" id="NOSEEUM">3.13. Instead of ads,
- now I get a checkerboard pattern. I don't want to see
- anything.</a></h3>
- <p>The replacement for blocked images can be controlled with the
- <a href="../user-manual/actions-file.html#SET-IMAGE-BLOCKER" target=
- "_top"><tt class="LITERAL">set-image-blocker</tt> action</a>. You have
- the choice of a checkerboard pattern, a transparent 1x1 GIF image (aka
- <span class="QUOTE">"blank"</span>), or a redirect to a custom image of
- your choice. Note that this choice only has effect for images which are
- blocked as images, i.e. whose URLs match both a <tt class=
- "LITERAL"><a href="../user-manual/actions-file.html#HANDLE-AS-IMAGE"
- target="_top">handle-as-image</a></tt> <span class="emphasis"><i class=
- "EMPHASIS">and</i></span> <tt class="LITERAL"><a href=
- "../user-manual/actions-file.html#BLOCK" target="_top">block</a></tt>
- action.</p>
- <p>If you want to see nothing, then change the <a href=
- "../user-manual/actions-file.html#SET-IMAGE-BLOCKER" target=
- "_top"><tt class="LITERAL">set-image-blocker</tt> action</a> to
- <span class="QUOTE">"blank"</span>. This can be done by editing the
- <tt class="FILENAME">user.action</tt> file, or through the <a href=
- "http://config.privoxy.org/show-status" target="_top">web-based actions
- file editor</a>.</p>
+ <h3 class="SECT2"><a name="NOSEEUM" id="NOSEEUM">3.13. Instead of ads, now I get a checkerboard pattern. I don't
+ want to see anything.</a></h3>
+ <p>The replacement for blocked images can be controlled with the <a href=
+ "../user-manual/actions-file.html#SET-IMAGE-BLOCKER" target="_top"><tt class="LITERAL">set-image-blocker</tt>
+ action</a>. You have the choice of a checkerboard pattern, a transparent 1x1 GIF image (aka <span class=
+ "QUOTE">"blank"</span>), or a redirect to a custom image of your choice. Note that this choice only has effect
+ for images which are blocked as images, i.e. whose URLs match both a <tt class="LITERAL"><a href=
+ "../user-manual/actions-file.html#HANDLE-AS-IMAGE" target="_top">handle-as-image</a></tt> <span class=
+ "emphasis"><i class="EMPHASIS">and</i></span> <tt class="LITERAL"><a href=
+ "../user-manual/actions-file.html#BLOCK" target="_top">block</a></tt> action.</p>
+ <p>If you want to see nothing, then change the <a href="../user-manual/actions-file.html#SET-IMAGE-BLOCKER"
+ target="_top"><tt class="LITERAL">set-image-blocker</tt> action</a> to <span class="QUOTE">"blank"</span>. This
+ can be done by editing the <tt class="FILENAME">user.action</tt> file, or through the <a href=
+ "http://config.privoxy.org/show-status" target="_top">web-based actions file editor</a>.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="WHYSEEUM" id="WHYSEEUM">3.14. Why would
- anybody want to see a checkerboard pattern?</a></h3>
- <p>Remember that <a href="general.html#WHATSANAD">telling which image
- is an ad and which isn't</a>, is an educated guess. While we hope that
- the standard configuration is rather smart, it will make occasional
- mistakes. The checkerboard image is visually decent, and it shows you
- where images have been blocked, which can be very helpful in case some
- navigation aid or otherwise innocent image was erroneously blocked. It
- is recommended for new users so they can <span class=
- "QUOTE">"see"</span> what is happening. Some people might also enjoy
- seeing how many banners they <span class="emphasis"><i class=
- "EMPHASIS">don't</i></span> have to see.</p>
+ <h3 class="SECT2"><a name="WHYSEEUM" id="WHYSEEUM">3.14. Why would anybody want to see a checkerboard
+ pattern?</a></h3>
+ <p>Remember that <a href="general.html#WHATSANAD">telling which image is an ad and which isn't</a>, is an
+ educated guess. While we hope that the standard configuration is rather smart, it will make occasional mistakes.
+ The checkerboard image is visually decent, and it shows you where images have been blocked, which can be very
+ helpful in case some navigation aid or otherwise innocent image was erroneously blocked. It is recommended for
+ new users so they can <span class="QUOTE">"see"</span> what is happening. Some people might also enjoy seeing how
+ many banners they <span class="emphasis"><i class="EMPHASIS">don't</i></span> have to see.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="BLOCKEDBYTEXT" id="BLOCKEDBYTEXT">3.15. I
- see some images being replaced with text instead of the checkerboard
- image. Why and how do I get rid of this?</a></h3>
- <p>This happens when the banners are not embedded in the HTML code of
- the page itself, but in separate HTML (sub)documents that are loaded
- into (i)frames or (i)layers, and these external HTML documents are
- blocked. Being non-images they get replaced by a substitute HTML page
- rather than a substitute image, which wouldn't work out technically,
- since the browser expects and accepts only HTML when it has requested
- an HTML document.</p>
- <p>The substitute page adapts to the available space and shows itself
- as a miniature two-liner if loaded into small frames, or full-blown
- with a large red "BLOCKED" banner if space allows.</p>
- <p>If you prefer the banners to be blocked by images, you must see to
- it that the HTML documents in which they are embedded are not blocked.
- Clicking the <span class="QUOTE">"See why"</span> link offered in the
- substitute page will show you which rule blocked the page. After
- changing the rule and un-blocking the HTML documents, the browser will
- try to load the actual banner images and the usual image blocking will
- (hopefully!) kick in.</p>
+ <h3 class="SECT2"><a name="BLOCKEDBYTEXT" id="BLOCKEDBYTEXT">3.15. I see some images being replaced with text
+ instead of the checkerboard image. Why and how do I get rid of this?</a></h3>
+ <p>This happens when the banners are not embedded in the HTML code of the page itself, but in separate HTML
+ (sub)documents that are loaded into (i)frames or (i)layers, and these external HTML documents are blocked. Being
+ non-images they get replaced by a substitute HTML page rather than a substitute image, which wouldn't work out
+ technically, since the browser expects and accepts only HTML when it has requested an HTML document.</p>
+ <p>The substitute page adapts to the available space and shows itself as a miniature two-liner if loaded into
+ small frames, or full-blown with a large red "BLOCKED" banner if space allows.</p>
+ <p>If you prefer the banners to be blocked by images, you must see to it that the HTML documents in which they
+ are embedded are not blocked. Clicking the <span class="QUOTE">"See why"</span> link offered in the substitute
+ page will show you which rule blocked the page. After changing the rule and un-blocking the HTML documents, the
+ browser will try to load the actual banner images and the usual image blocking will (hopefully!) kick in.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="SRVANY" id="SRVANY">3.16. Can Privoxy run as
- a service on Win2K/NT/XP?</a></h3>
- <p>Yes. Version 3.0.5 introduces full <span class=
- "APPLICATION">Windows</span> service functionality. See <a href=
- "../user-manual/installation.html#installation-pack-win" target=
- "_top">the <i class="CITETITLE">User Manual</i></a> for details on how
- to install and configure <span class="APPLICATION">Privoxy</span> as a
+ <h3 class="SECT2"><a name="SRVANY" id="SRVANY">3.16. Can Privoxy run as a service on Win2K/NT/XP?</a></h3>
+ <p>Yes. Version 3.0.5 introduces full <span class="APPLICATION">Windows</span> service functionality. See
+ <a href="../user-manual/installation.html#installation-pack-win" target="_top">the <i class="CITETITLE">User
+ Manual</i></a> for details on how to install and configure <span class="APPLICATION">Privoxy</span> as a
service.</p>
- <p>Earlier 3.x versions could run as a system service using <b class=
- "COMMAND">srvany.exe</b>. See the discussion at <a href=
- "https://sourceforge.net/tracker/?func=detail&atid=361118&aid=485617&group_id=11118"
- target=
- "_top">https://sourceforge.net/tracker/?func=detail&atid=361118&aid=485617&group_id=11118</a>,
+ <p>Earlier 3.x versions could run as a system service using <b class="COMMAND">srvany.exe</b>. See the discussion
+ at <a href="https://sourceforge.net/tracker/?func=detail&atid=361118&aid=485617&group_id=11118"
+ target="_top">https://sourceforge.net/tracker/?func=detail&atid=361118&aid=485617&group_id=11118</a>,
for details, and a sample configuration.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="OTHERPROXY" id="OTHERPROXY">3.17. How can I
- make Privoxy work with other proxies?</a></h3>
- <p>This can be done and is often useful to combine the benefits of
- <span class="APPLICATION">Privoxy</span> with those of a another proxy,
- for example to cache content. See the <a href=
- "../user-manual/config.html#FORWARDING" target="_top">forwarding
- chapter</a> in the <a href="../user-manual/index.html" target=
- "_top">User Manual</a> which describes how to do this. If you intend to
- use Privoxy with Tor, please also have a look at <a href=
+ <h3 class="SECT2"><a name="OTHERPROXY" id="OTHERPROXY">3.17. How can I make Privoxy work with other
+ proxies?</a></h3>
+ <p>This can be done and is often useful to combine the benefits of <span class="APPLICATION">Privoxy</span> with
+ those of a another proxy, for example to cache content. See the <a href="../user-manual/config.html#FORWARDING"
+ target="_top">forwarding chapter</a> in the <a href="../user-manual/index.html" target="_top">User Manual</a>
+ which describes how to do this. If you intend to use Privoxy with Tor, please also have a look at <a href=
"misc.html#TOR">How do I use Privoxy together with Tor</a>.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="PORT-80" id="PORT-80">3.18. Can I just set
- Privoxy to use port 80 and thus avoid individual browser
- configuration?</a></h3>
- <p>No, its more complicated than that. This only works with special
- kinds of proxies known as <span class="QUOTE">"intercepting"</span>
- proxies (<a href="configuration.html#INTERCEPTING">see below</a>).</p>
+ <h3 class="SECT2"><a name="PORT-80" id="PORT-80">3.18. Can I just set Privoxy to use port 80 and thus avoid
+ individual browser configuration?</a></h3>
+ <p>No, its more complicated than that. This only works with special kinds of proxies known as <span class=
+ "QUOTE">"intercepting"</span> proxies (<a href="configuration.html#INTERCEPTING">see below</a>).</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="TRANSPARENT" id="TRANSPARENT">3.19. Can
- Privoxy run as a <span class="QUOTE">"transparent"</span>
- proxy?</a></h3>
- <p>The whole idea of Privoxy is to modify client requests and server
- responses in all sorts of ways and therefore it's not a transparent
- proxy as described in <a href="http://tools.ietf.org/html/rfc2616"
- target="_top">RFC 2616</a>.</p>
- <p>However, some people say <span class="QUOTE">"transparent
- proxy"</span> when they mean <span class="QUOTE">"intercepting
- proxy"</span>. If you are one of them, please read the <a href=
+ <h3 class="SECT2"><a name="TRANSPARENT" id="TRANSPARENT">3.19. Can Privoxy run as a <span class=
+ "QUOTE">"transparent"</span> proxy?</a></h3>
+ <p>The whole idea of Privoxy is to modify client requests and server responses in all sorts of ways and therefore
+ it's not a transparent proxy as described in <a href="http://tools.ietf.org/html/rfc2616" target="_top">RFC
+ 2616</a>.</p>
+ <p>However, some people say <span class="QUOTE">"transparent proxy"</span> when they mean <span class=
+ "QUOTE">"intercepting proxy"</span>. If you are one of them, please read the <a href=
"configuration.html#INTERCEPTING">next entry</a>.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="INTERCEPTING" id="INTERCEPTING">3.20. Can
- Privoxy run as a <span class="QUOTE">"intercepting"</span>
- proxy?</a></h3>
- <p><span class="APPLICATION">Privoxy</span> can't intercept traffic
- itself, but it can handle requests that where intercepted and
- redirected with a packet filter (like <span class=
- "APPLICATION">PF</span> or <span class="APPLICATION">iptables</span>),
- as long as the <tt class="LITERAL">Host</tt> header is present.</p>
- <p>As the <tt class="LITERAL">Host</tt> header is required by HTTP/1.1
- and as most web sites rely on it anyway, this limitation shouldn't be a
- problem.</p>
- <p>Please refer to your packet filter's documentation to learn how to
- intercept and redirect traffic into <span class=
- "APPLICATION">Privoxy</span>. Afterward you just have to configure
- <span class="APPLICATION">Privoxy</span> to <a href=
- "../user-manual/config.html#ACCEPT-INTERCEPTED-REQUESTS" target=
+ <h3 class="SECT2"><a name="INTERCEPTING" id="INTERCEPTING">3.20. Can Privoxy run as a <span class=
+ "QUOTE">"intercepting"</span> proxy?</a></h3>
+ <p><span class="APPLICATION">Privoxy</span> can't intercept traffic itself, but it can handle requests that where
+ intercepted and redirected with a packet filter (like <span class="APPLICATION">PF</span> or <span class=
+ "APPLICATION">iptables</span>), as long as the <tt class="LITERAL">Host</tt> header is present.</p>
+ <p>As the <tt class="LITERAL">Host</tt> header is required by HTTP/1.1 and as most web sites rely on it anyway,
+ this limitation shouldn't be a problem.</p>
+ <p>Please refer to your packet filter's documentation to learn how to intercept and redirect traffic into
+ <span class="APPLICATION">Privoxy</span>. Afterward you just have to configure <span class=
+ "APPLICATION">Privoxy</span> to <a href="../user-manual/config.html#ACCEPT-INTERCEPTED-REQUESTS" target=
"_top">accept intercepted requests</a>.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="OUTLOOK" id="OUTLOOK">3.21. How can I
- configure Privoxy for use with Outlook?</a></h3>
- <p>Versions of <span class="APPLICATION">Outlook</span> prior to Office
- 2007, use <span class="APPLICATION">Internet Explorer</span> components
- to both render HTML, and fetch any HTTP requests that may be embedded
- in an HTML email. So however you have <span class=
- "APPLICATION">Privoxy</span> configured to work with IE, this
- configuration should automatically be shared, at least with older
- version of Internet Explorer.</p>
- <p>Starting with Office 2007, Microsoft is instead using the MS-Word
- rendering engine with Outlook. It is unknown whether this can be
- configured to use a proxy.</p>
+ <h3 class="SECT2"><a name="OUTLOOK" id="OUTLOOK">3.21. How can I configure Privoxy for use with Outlook?</a></h3>
+ <p>Versions of <span class="APPLICATION">Outlook</span> prior to Office 2007, use <span class=
+ "APPLICATION">Internet Explorer</span> components to both render HTML, and fetch any HTTP requests that may be
+ embedded in an HTML email. So however you have <span class="APPLICATION">Privoxy</span> configured to work with
+ IE, this configuration should automatically be shared, at least with older version of Internet Explorer.</p>
+ <p>Starting with Office 2007, Microsoft is instead using the MS-Word rendering engine with Outlook. It is unknown
+ whether this can be configured to use a proxy.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="OUTLOOK-MORE" id="OUTLOOK-MORE">3.22. How
- can I have separate rules just for HTML mail?</a></h3>
- <p>The short answer is, you can't. <span class=
- "APPLICATION">Privoxy</span> has no way of knowing which particular
- application makes a request, so there is no way to distinguish between
- web pages and HTML mail. <span class="APPLICATION">Privoxy</span> just
- blindly proxies all requests. In the case of <span class=
- "APPLICATION">Outlook Express</span> (see above), OE uses IE anyway,
- and there is no way for <span class="APPLICATION">Privoxy</span> to
- ever be able to distinguish between them (nor could any other proxy
- type application for that matter).</p>
- <p>For a good discussion of some of the issues involved (including
- privacy and security issues), see <a href=
- "https://sourceforge.net/tracker/?func=detail&atid=211118&aid=629518&group_id=11118"
- target=
+ <h3 class="SECT2"><a name="OUTLOOK-MORE" id="OUTLOOK-MORE">3.22. How can I have separate rules just for HTML
+ mail?</a></h3>
+ <p>The short answer is, you can't. <span class="APPLICATION">Privoxy</span> has no way of knowing which
+ particular application makes a request, so there is no way to distinguish between web pages and HTML mail.
+ <span class="APPLICATION">Privoxy</span> just blindly proxies all requests. In the case of <span class=
+ "APPLICATION">Outlook Express</span> (see above), OE uses IE anyway, and there is no way for <span class=
+ "APPLICATION">Privoxy</span> to ever be able to distinguish between them (nor could any other proxy type
+ application for that matter).</p>
+ <p>For a good discussion of some of the issues involved (including privacy and security issues), see <a href=
+ "https://sourceforge.net/tracker/?func=detail&atid=211118&aid=629518&group_id=11118" target=
"_top">https://sourceforge.net/tracker/?func=detail&atid=211118&aid=629518&group_id=11118</a>.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="SNEAKY-COOKIES" id="SNEAKY-COOKIES">3.23. I
- sometimes notice cookies sneaking through. How?</a></h3>
- <p><a href="http://en.wikipedia.org/wiki/Browser_cookie" target=
- "_top">Cookies</a> can be set in several ways. The classic method is
- via the <tt class="LITERAL">Set-Cookie</tt> HTTP header. This is
- straightforward, and an easy one to manipulate, such as the
- <span class="APPLICATION">Privoxy</span> concept of <a href=
- "../user-manual/actions-file.html#SESSION-COOKIES-ONLY" target=
- "_top">session-cookies-only</a>. There is also the possibility of using
- <a href="http://en.wikipedia.org/wiki/Javascript" target=
- "_top">Javascript</a> to set cookies (<span class=
- "APPLICATION">Privoxy</span> calls these <tt class=
- "LITERAL">content-cookies</tt>). This is trickier because the syntax
- can vary widely, and thus requires a certain amount of guesswork. It is
- not realistic to catch all of these short of disabling Javascript,
- which would break many sites. And lastly, if the cookies are embedded
- in a HTTPS/SSL secure session via Javascript, they are beyond
- <span class="APPLICATION">Privoxy's</span> reach.</p>
- <p>All in all, <span class="APPLICATION">Privoxy</span> can help manage
- cookies in general, can help minimize the loss of privacy posed by
- cookies, but can't realistically stop all cookies.</p>
+ <h3 class="SECT2"><a name="SNEAKY-COOKIES" id="SNEAKY-COOKIES">3.23. I sometimes notice cookies sneaking through.
+ How?</a></h3>
+ <p><a href="http://en.wikipedia.org/wiki/Browser_cookie" target="_top">Cookies</a> can be set in several ways.
+ The classic method is via the <tt class="LITERAL">Set-Cookie</tt> HTTP header. This is straightforward, and an
+ easy one to manipulate, such as the <span class="APPLICATION">Privoxy</span> concept of <a href=
+ "../user-manual/actions-file.html#SESSION-COOKIES-ONLY" target="_top">session-cookies-only</a>. There is also the
+ possibility of using <a href="http://en.wikipedia.org/wiki/Javascript" target="_top">Javascript</a> to set
+ cookies (<span class="APPLICATION">Privoxy</span> calls these <tt class="LITERAL">content-cookies</tt>). This is
+ trickier because the syntax can vary widely, and thus requires a certain amount of guesswork. It is not realistic
+ to catch all of these short of disabling Javascript, which would break many sites. And lastly, if the cookies are
+ embedded in a HTTPS/SSL secure session via Javascript, they are beyond <span class="APPLICATION">Privoxy's</span>
+ reach.</p>
+ <p>All in all, <span class="APPLICATION">Privoxy</span> can help manage cookies in general, can help minimize the
+ loss of privacy posed by cookies, but can't realistically stop all cookies.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="EVIL-COOKIES" id="EVIL-COOKIES">3.24. Are
- all cookies bad? Why?</a></h3>
- <p>No, in fact there are many beneficial uses of <a href=
- "http://en.wikipedia.org/wiki/Browser_cookie" target=
- "_top">cookies</a>. Cookies are just a method that browsers can use to
- store data between pages, or between browser sessions. Sometimes there
- is a good reason for this, and the user's life is a bit easier as a
- result. But there is a long history of some websites taking advantage
- of this layer of trust, and using the data they glean from you and your
- browsing habits for their own purposes, and maybe to your potential
- detriment. Such sites are using you and storing their data on your
- system. That is why the privacy conscious watch from whom those cookies
- come, and why they really <span class="emphasis"><i class=
- "EMPHASIS">need</i></span> to be there.</p>
- <p>See the <a href="http://en.wikipedia.org/wiki/Browser_cookie"
- target="_top">Wikipedia cookie definition</a> for more.</p>
+ <h3 class="SECT2"><a name="EVIL-COOKIES" id="EVIL-COOKIES">3.24. Are all cookies bad? Why?</a></h3>
+ <p>No, in fact there are many beneficial uses of <a href="http://en.wikipedia.org/wiki/Browser_cookie" target=
+ "_top">cookies</a>. Cookies are just a method that browsers can use to store data between pages, or between
+ browser sessions. Sometimes there is a good reason for this, and the user's life is a bit easier as a result. But
+ there is a long history of some websites taking advantage of this layer of trust, and using the data they glean
+ from you and your browsing habits for their own purposes, and maybe to your potential detriment. Such sites are
+ using you and storing their data on your system. That is why the privacy conscious watch from whom those cookies
+ come, and why they really <span class="emphasis"><i class="EMPHASIS">need</i></span> to be there.</p>
+ <p>See the <a href="http://en.wikipedia.org/wiki/Browser_cookie" target="_top">Wikipedia cookie definition</a>
+ for more.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="ALLOW-COOKIES" id="ALLOW-COOKIES">3.25. How
- can I allow permanent cookies for my trusted sites?</a></h3>
- <p>There are several actions that relate to cookies. The default
- behavior is to allow only <span class="QUOTE">"session cookies"</span>,
- which means the cookies only last for the current browser session. This
- eliminates most kinds of abuse related to cookies. But there may be
- cases where you want cookies to last.</p>
- <p>To disable all cookie actions, so that cookies are allowed
- unrestricted, both in and out, for <tt class=
+ <h3 class="SECT2"><a name="ALLOW-COOKIES" id="ALLOW-COOKIES">3.25. How can I allow permanent cookies for my
+ trusted sites?</a></h3>
+ <p>There are several actions that relate to cookies. The default behavior is to allow only <span class=
+ "QUOTE">"session cookies"</span>, which means the cookies only last for the current browser session. This
+ eliminates most kinds of abuse related to cookies. But there may be cases where you want cookies to last.</p>
+ <p>To disable all cookie actions, so that cookies are allowed unrestricted, both in and out, for <tt class=
"LITERAL">example.com</tt>:</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
</td>
</tr>
</table>
- <p>Place the above in <tt class="FILENAME">user.action</tt>. Note that
- some of these may be off by default anyway, so this might be redundant,
- but there is no harm being explicit in what you want to happen.
- <tt class="FILENAME">user.action</tt> includes an alias for this
- situation, called <tt class="LITERAL">allow-all-cookies</tt>.</p>
+ <p>Place the above in <tt class="FILENAME">user.action</tt>. Note that some of these may be off by default
+ anyway, so this might be redundant, but there is no harm being explicit in what you want to happen. <tt class=
+ "FILENAME">user.action</tt> includes an alias for this situation, called <tt class=
+ "LITERAL">allow-all-cookies</tt>.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="MULTIPLES" id="MULTIPLES">3.26. Can I have
- separate configurations for different users?</a></h3>
- <p>Each instance of <span class="APPLICATION">Privoxy</span> has its
- own configuration, including such attributes as the TCP port that it
- listens on. What you can do is run multiple instances of <span class=
- "APPLICATION">Privoxy</span>, each with a unique <a href=
- "../user-manual/config.html#LISTEN-ADDRESS" target=
- "_top">listen-address</a> configuration setting, and configuration
- path, and then each of these can have their own configurations. Think
- of it as per-port configuration.</p>
- <p>Simple enough for a few users, but for large installations, consider
- having groups of users that might share like configurations.</p>
+ <h3 class="SECT2"><a name="MULTIPLES" id="MULTIPLES">3.26. Can I have separate configurations for different
+ users?</a></h3>
+ <p>Each instance of <span class="APPLICATION">Privoxy</span> has its own configuration, including such attributes
+ as the TCP port that it listens on. What you can do is run multiple instances of <span class=
+ "APPLICATION">Privoxy</span>, each with a unique <a href="../user-manual/config.html#LISTEN-ADDRESS" target=
+ "_top">listen-address</a> configuration setting, and configuration path, and then each of these can have their
+ own configurations. Think of it as per-port configuration.</p>
+ <p>Simple enough for a few users, but for large installations, consider having groups of users that might share
+ like configurations.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="WHITELISTS" id="WHITELISTS">3.27. Can I
- set-up Privoxy as a whitelist of <span class="QUOTE">"good"</span>
- sites?</a></h3>
- <p>Sure. There are a couple of things you can do for simple
- white-listing. Here's one real easy one:</p>
+ <h3 class="SECT2"><a name="WHITELISTS" id="WHITELISTS">3.27. Can I set-up Privoxy as a whitelist of <span class=
+ "QUOTE">"good"</span> sites?</a></h3>
+ <p>Sure. There are a couple of things you can do for simple white-listing. Here's one real easy one:</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
- <pre class="SCREEN">
- ############################################################
+ <pre class="SCREEN"> ############################################################
# Blacklist
############################################################
- { <a href="../user-manual/actions-file.html#BLOCK" target=
-"_top">+block</a> }
+ { <a href="../user-manual/actions-file.html#BLOCK" target="_top">+block</a> }
/ # Block *all* URLs
############################################################
# Whitelist
############################################################
- { <a href="../user-manual/actions-file.html#BLOCK" target=
-"_top">-block</a> }
+ { <a href="../user-manual/actions-file.html#BLOCK" target="_top">-block</a> }
kids.example.com
toys.example.com
games.example.com</pre>
</td>
</tr>
</table>
- <p>This allows access to only those three sites by first blocking all
- URLs, and then subsequently allowing three specific exceptions.</p>
- <p>Another approach is <span class="APPLICATION">Privoxy's</span>
- <tt class="LITERAL">trustfile</tt> concept, which incorporates the
- notion of <span class="QUOTE">"trusted referrers"</span>. See the
- <a href="../user-manual/config.html#TRUSTFILE" target="_top">Trust
- documentation</a> for details.</p>
- <p>These are fairly simple approaches and are not completely foolproof.
- There are various other configuration options that should be disabled
- (described elsewhere here and in <a href="../user-manual/" target=
- "_top">the User Manual</a>) so that users can't modify their own
- configuration and easily circumvent the whitelist.</p>
+ <p>This allows access to only those three sites by first blocking all URLs, and then subsequently allowing three
+ specific exceptions.</p>
+ <p>Another approach is <span class="APPLICATION">Privoxy's</span> <tt class="LITERAL">trustfile</tt> concept,
+ which incorporates the notion of <span class="QUOTE">"trusted referrers"</span>. See the <a href=
+ "../user-manual/config.html#TRUSTFILE" target="_top">Trust documentation</a> for details.</p>
+ <p>These are fairly simple approaches and are not completely foolproof. There are various other configuration
+ options that should be disabled (described elsewhere here and in <a href="../user-manual/" target="_top">the User
+ Manual</a>) so that users can't modify their own configuration and easily circumvent the whitelist.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="NO-ADBLOCK" id="NO-ADBLOCK">3.28. How can I
- turn off ad-blocking?</a></h3>
- <p>Ad blocking is achieved through a complex application of various
- <span class="APPLICATION">Privoxy</span> <a href=
- "../user-manual/actions-file.html" target="_top">actions</a>. These
- actions are deployed against simple images, banners, flash animations,
- text pages, JavaScript, pop-ups and pop-unders, etc., so its not as
- simple as just turning one or two actions off. The various actions that
- make up <span class="APPLICATION">Privoxy</span> ad blocking are
- hard-coded into the default configuration files. It has been assumed
- that everyone using <span class="APPLICATION">Privoxy</span> is
- interested in this particular feature.</p>
- <p>If you want to do without this, there are several approaches you can
- take: You can manually undo the many block rules in <tt class=
- "FILENAME">default.action</tt>. Or even easier, just create your own
- <tt class="FILENAME">default.action</tt> file from scratch without the
- many ad blocking rules, and corresponding exceptions. Or lastly, if you
- are not concerned about the additional blocks that are done for privacy
- reasons, you can very easily over-ride <span class="emphasis"><i class=
- "EMPHASIS">all</i></span> blocking with the following very simple rule
- in your <tt class="FILENAME">user.action</tt>:</p>
+ <h3 class="SECT2"><a name="NO-ADBLOCK" id="NO-ADBLOCK">3.28. How can I turn off ad-blocking?</a></h3>
+ <p>Ad blocking is achieved through a complex application of various <span class="APPLICATION">Privoxy</span>
+ <a href="../user-manual/actions-file.html" target="_top">actions</a>. These actions are deployed against simple
+ images, banners, flash animations, text pages, JavaScript, pop-ups and pop-unders, etc., so its not as simple as
+ just turning one or two actions off. The various actions that make up <span class="APPLICATION">Privoxy</span> ad
+ blocking are hard-coded into the default configuration files. It has been assumed that everyone using
+ <span class="APPLICATION">Privoxy</span> is interested in this particular feature.</p>
+ <p>If you want to do without this, there are several approaches you can take: You can manually undo the many
+ block rules in <tt class="FILENAME">default.action</tt>. Or even easier, just create your own <tt class=
+ "FILENAME">default.action</tt> file from scratch without the many ad blocking rules, and corresponding
+ exceptions. Or lastly, if you are not concerned about the additional blocks that are done for privacy reasons,
+ you can very easily over-ride <span class="emphasis"><i class="EMPHASIS">all</i></span> blocking with the
+ following very simple rule in your <tt class="FILENAME">user.action</tt>:</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
<pre class="SCREEN"> # Unblock everybody, everywhere
- { <a href="../user-manual/actions-file.html#BLOCK" target=
-"_top">-block</a> }
+ { <a href="../user-manual/actions-file.html#BLOCK" target="_top">-block</a> }
/ # UN-Block *all* URLs</pre>
</td>
</tr>
</table>
- <p>Or even a more comprehensive reversing of various ad related
- actions:</p>
+ <p>Or even a more comprehensive reversing of various ad related actions:</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
- <pre class="SCREEN">
- # Unblock everybody, everywhere, and turn off appropriate filtering, etc
- { <a href="../user-manual/actions-file.html#BLOCK" target=
-"_top">-block</a> \
- <a href="../user-manual/actions-file.html#FILTER-BANNERS-BY-SIZE" target=
-"_top">-filter{banners-by-size}</a> \
- <a href="../user-manual/actions-file.html#FILTER-BANNERS-BY-LINK" target=
-"_top">-filter{banners-by-link}</a> \
+ <pre class="SCREEN"> # Unblock everybody, everywhere, and turn off appropriate filtering, etc
+ { <a href="../user-manual/actions-file.html#BLOCK" target="_top">-block</a> \
+ <a href="../user-manual/actions-file.html#FILTER-BANNERS-BY-SIZE" target="_top">-filter{banners-by-size}</a> \
+ <a href="../user-manual/actions-file.html#FILTER-BANNERS-BY-LINK" target="_top">-filter{banners-by-link}</a> \
<tt class="LITERAL">allow-popups</tt> \
}
/ # UN-Block *all* URLs and allow ads</pre>
</td>
</tr>
</table>
- <p>This last <span class="QUOTE">"action"</span> in this compound
- statement, <tt class="LITERAL">allow-popups</tt>, is an <a href=
- "../user-manual/actions-file.html#ALIASES" target="_top">alias</a> that
- disables various pop-up blocking features.</p>
+ <p>This last <span class="QUOTE">"action"</span> in this compound statement, <tt class=
+ "LITERAL">allow-popups</tt>, is an <a href="../user-manual/actions-file.html#ALIASES" target="_top">alias</a>
+ that disables various pop-up blocking features.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="TEMPLATES" id="TEMPLATES">3.29. How can I
- have custom template pages, like the <span class="emphasis"><i class=
- "EMPHASIS">BLOCKED</i></span> page?</a></h3>
- <p><span class="APPLICATION">Privoxy</span> <span class=
- "QUOTE">"templates"</span> are specialized text files utilized by
- <span class="APPLICATION">Privoxy</span> for various purposes and can
- easily be modified using any text editor. All the template pages are
- installed in a sub-directory appropriately named: <tt class=
- "FILENAME">templates</tt>. Knowing something about HTML syntax will of
- course be helpful.</p>
- <p>Be forewarned that the default templates are subject to being
- overwritten during upgrades. You can, however, create completely new
- templates, place them in another directory and specify the alternate
- path in the main <tt class="FILENAME">config</tt>. For details, have a
- look at the <a href="../user-manual/config.html#templdir" target=
- "_top">templdir</a> option.</p>
+ <h3 class="SECT2"><a name="TEMPLATES" id="TEMPLATES">3.29. How can I have custom template pages, like the
+ <span class="emphasis"><i class="EMPHASIS">BLOCKED</i></span> page?</a></h3>
+ <p><span class="APPLICATION">Privoxy</span> <span class="QUOTE">"templates"</span> are specialized text files
+ utilized by <span class="APPLICATION">Privoxy</span> for various purposes and can easily be modified using any
+ text editor. All the template pages are installed in a sub-directory appropriately named: <tt class=
+ "FILENAME">templates</tt>. Knowing something about HTML syntax will of course be helpful.</p>
+ <p>Be forewarned that the default templates are subject to being overwritten during upgrades. You can, however,
+ create completely new templates, place them in another directory and specify the alternate path in the main
+ <tt class="FILENAME">config</tt>. For details, have a look at the <a href="../user-manual/config.html#templdir"
+ target="_top">templdir</a> option.</p>
</div>
<div class="SECT2">
- <h3 class="SECT2"><a name="BLOCKALL" id="BLOCKALL">3.30. How can I
- remove the <span class="QUOTE">"Go There Anyway"</span> link from the
- <span class="emphasis"><i class="EMPHASIS">BLOCKED</i></span>
- page?</a></h3>
- <p>There is more than one way to do it (although Perl is not
- involved).</p>
- <p>Editing the BLOCKED template page (see above) may dissuade some
- users, but this method is easily circumvented. Where you need this
- level of control, you might want to build <span class=
- "APPLICATION">Privoxy</span> from source, and disable various features
- that are available as compile-time options. You should <b class=
+ <h3 class="SECT2"><a name="BLOCKALL" id="BLOCKALL">3.30. How can I remove the <span class="QUOTE">"Go There
+ Anyway"</span> link from the <span class="emphasis"><i class="EMPHASIS">BLOCKED</i></span> page?</a></h3>
+ <p>There is more than one way to do it (although Perl is not involved).</p>
+ <p>Editing the BLOCKED template page (see above) may dissuade some users, but this method is easily circumvented.
+ Where you need this level of control, you might want to build <span class="APPLICATION">Privoxy</span> from
+ source, and disable various features that are available as compile-time options. You should <b class=
"COMMAND">configure</b> the sources as follows:</p>
<table border="0" bgcolor="#E0E0E0" width="100%">
<tr>
<td>
- <pre class="SCREEN">
- ./configure --disable-toggle --disable-editor --disable-force</pre>
+ <pre class="SCREEN"> ./configure --disable-toggle --disable-editor --disable-force</pre>
</td>
</tr>
</table>
- <p>This will create an executable with hard-coded security features so
- that <span class="APPLICATION">Privoxy</span> does not allow easy
- bypassing of blocked sites, or changing the current configuration via
- any connected user's web browser.</p>
- <p>Finally, all of these features can also be toggled on/off via
- options in <span class="APPLICATION">Privoxy's</span> main <a href=
- "../user-manual/config.html#ACCESS-CONTROL" target="_top">config</a>
+ <p>This will create an executable with hard-coded security features so that <span class=
+ "APPLICATION">Privoxy</span> does not allow easy bypassing of blocked sites, or changing the current
+ configuration via any connected user's web browser.</p>
+ <p>Finally, all of these features can also be toggled on/off via options in <span class=
+ "APPLICATION">Privoxy's</span> main <a href="../user-manual/config.html#ACCESS-CONTROL" target="_top">config</a>
file which means you don't have to recompile anything.</p>
</div>
</div>
<div class="NAVFOOTER">
<hr align="left" width="100%">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
+ <table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
- <td width="33%" align="left" valign="top"><a href="installation.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="misc.html"
- accesskey="N">Next</a></td>
+ <td width="33%" align="left" valign="top"><a href="installation.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="misc.html" accesskey="N">Next</a></td>
</tr>
<tr>
<td width="33%" align="left" valign="top">Installation</td>
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
- <title>Contacting the developers, Bug Reporting and Feature
- Requests</title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
- <link rel="HOME" title="Privoxy Frequently Asked Questions" href=
- "index.html">
+ <title>Contacting the developers, Bug Reporting and Feature Requests</title>
+ <meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
+ <link rel="HOME" title="Privoxy Frequently Asked Questions" href="index.html">
<link rel="PREVIOUS" title="Troubleshooting" href="trouble.html">
- <link rel="NEXT" title="Privoxy Copyright, License and History" href=
- "copyright.html">
+ <link rel="NEXT" title="Privoxy Copyright, License and History" href="copyright.html">
<link rel="STYLESHEET" type="text/css" href="../p_doc.css">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
-<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
-"#840084" alink="#0000FF">
+<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">
+ <table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
- <th colspan="3" align="center">Privoxy Frequently Asked
- Questions</th>
+ <th colspan="3" align="center">Privoxy Frequently Asked Questions</th>
</tr>
<tr>
- <td width="10%" align="left" valign="bottom"><a href="trouble.html"
- accesskey="P">Prev</a></td>
+ <td width="10%" align="left" valign="bottom"><a href="trouble.html" accesskey="P">Prev</a></td>
<td width="80%" align="center" valign="bottom"></td>
- <td width="10%" align="right" valign="bottom"><a href=
- "copyright.html" accesskey="N">Next</a></td>
+ <td width="10%" align="right" valign="bottom"><a href="copyright.html" accesskey="N">Next</a></td>
</tr>
</table>
<hr align="left" width="100%">
</div>
<div class="SECT1">
- <h1 class="SECT1"><a name="CONTACT" id="CONTACT">6. Contacting the
- developers, Bug Reporting and Feature Requests</a></h1>
- <p>We value your feedback. In fact, we rely on it to improve <span class=
- "APPLICATION">Privoxy</span> and its configuration. However, please note
- the following hints, so we can provide you with the best support.</p>
+ <h1 class="SECT1"><a name="CONTACT" id="CONTACT">6. Contacting the developers, Bug Reporting and Feature
+ Requests</a></h1>
+ <p>We value your feedback. In fact, we rely on it to improve <span class="APPLICATION">Privoxy</span> and its
+ configuration. However, please note the following hints, so we can provide you with the best support.</p>
<div class="SECT2">
- <h2 class="SECT2"><a name="SUFFICIENT-INFORMATION" id=
- "SUFFICIENT-INFORMATION">6.1. Please provide sufficient
+ <h2 class="SECT2"><a name="SUFFICIENT-INFORMATION" id="SUFFICIENT-INFORMATION">6.1. Please provide sufficient
information</a></h2>
- <p>A lot of support requests don't contain enough information and can't
- be solved without a lot of back and forth which causes unnecessary
- delays. Reading this section should help to prevent that.</p>
- <p>Before contacting us to report a problem, please try to verify that
- it is a <span class="APPLICATION">Privoxy</span> problem, and not a
- browser or site problem or documented behaviour that just happens to be
- different than what you expected. If unsure, try <a href=
- "http://config.privoxy.org/toggle?set=disable" target="_top">toggling
- off</a> <span class="APPLICATION">Privoxy</span>, and see if the
- problem persists.</p>
- <p>If you are using your own custom configuration, please try the
- default configuration to see if the problem is configuration related.
- If you're having problems with a feature that is disabled by default,
- please ask around on the mailing list if others can reproduce the
- problem.</p>
- <p>If you aren't using the latest Privoxy version, the problem may have
- been found and fixed in the meantime. We would appreciate if you could
- take the time to <a href=
- "https://www.privoxy.org/user-manual/installation.html" target=
- "_top">upgrade to the latest version</a> and verify that the problem
- still exists.</p>
- <p>Please be sure to provide the following information when reporting
- problems or requesting support:</p>
+ <p>A lot of support requests don't contain enough information and can't be solved without a lot of back and forth
+ which causes unnecessary delays. Reading this section should help to prevent that.</p>
+ <p>Before contacting us to report a problem, please try to verify that it is a <span class=
+ "APPLICATION">Privoxy</span> problem, and not a browser or site problem or documented behaviour that just happens
+ to be different than what you expected. If unsure, try <a href="http://config.privoxy.org/toggle?set=disable"
+ target="_top">toggling off</a> <span class="APPLICATION">Privoxy</span>, and see if the problem persists.</p>
+ <p>If you are using your own custom configuration, please try the default configuration to see if the problem is
+ configuration related. If you're having problems with a feature that is disabled by default, please ask around on
+ the mailing list if others can reproduce the problem.</p>
+ <p>If you aren't using the latest Privoxy version, the problem may have been found and fixed in the meantime. We
+ would appreciate if you could take the time to <a href="https://www.privoxy.org/user-manual/installation.html"
+ target="_top">upgrade to the latest version</a> and verify that the problem still exists.</p>
+ <p>Please be sure to provide the following information when reporting problems or requesting support:</p>
<ul>
<li>
- <p>The exact <span class="APPLICATION">Privoxy</span> version you
- are using.</p>
+ <p>The exact <span class="APPLICATION">Privoxy</span> version you are using.</p>
</li>
<li>
- <p>The operating system and versions you run <span class=
- "APPLICATION">Privoxy</span> on, e.g. <span class=
+ <p>The operating system and versions you run <span class="APPLICATION">Privoxy</span> on, e.g. <span class=
"APPLICATION">Windows XP SP2</span>.</p>
</li>
<li>
- <p>The name, platform, and version of the <span class=
- "APPLICATION">browser</span> you were using (e.g. <span class=
- "APPLICATION">Internet Explorer v5.5</span> for Mac).</p>
+ <p>The name, platform, and version of the <span class="APPLICATION">browser</span> you were using (e.g.
+ <span class="APPLICATION">Internet Explorer v5.5</span> for Mac).</p>
</li>
<li>
- <p>The URL where the problem occurred, or some way for us to
- duplicate the problem (e.g. <tt class=
+ <p>The URL where the problem occurred, or some way for us to duplicate the problem (e.g. <tt class=
"LITERAL">http://somesite.example.com/?somethingelse=123</tt>).</p>
</li>
<li>
- <p>Whether your version of <span class="APPLICATION">Privoxy</span>
- is one supplied by the <span class="APPLICATION">Privoxy</span>
- developers via SourceForge, or if you got your copy somewhere
- else.</p>
+ <p>Whether your version of <span class="APPLICATION">Privoxy</span> is one supplied by the <span class=
+ "APPLICATION">Privoxy</span> developers via SourceForge, or if you got your copy somewhere else.</p>
</li>
<li>
- <p>Whether you are using <span class="APPLICATION">Privoxy</span>
- together with another proxy such as <span class=
- "APPLICATION">Tor</span>. If so, please temporary disable the other
- proxy to see if the symptoms change.</p>
+ <p>Whether you are using <span class="APPLICATION">Privoxy</span> together with another proxy such as
+ <span class="APPLICATION">Tor</span>. If so, please temporary disable the other proxy to see if the symptoms
+ change.</p>
</li>
<li>
- <p>Whether you are using a personal firewall product. If so, does
- <span class="APPLICATION">Privoxy</span> work without it?</p>
+ <p>Whether you are using a personal firewall product. If so, does <span class="APPLICATION">Privoxy</span>
+ work without it?</p>
</li>
<li>
- <p>Any other pertinent information to help identify the problem
- such as config or log file excerpts (yes, you should have log file
- entries for each action taken). To get a meaningful logfile, please
- make sure that the <a href="../user-manual/config.html#LOGFILE"
- target="_top">logfile directive</a> is being used and the following
- <a href="../user-manual/config.html#DEBUG" target="_top">debug
- options</a> are enabled (all of them):</p>
+ <p>Any other pertinent information to help identify the problem such as config or log file excerpts (yes, you
+ should have log file entries for each action taken). To get a meaningful logfile, please make sure that the
+ <a href="../user-manual/config.html#LOGFILE" target="_top">logfile directive</a> is being used and the
+ following <a href="../user-manual/config.html#DEBUG" target="_top">debug options</a> are enabled (all of
+ them):</p>
<p class="LITERALLAYOUT">
- debug 1 # Log the destination for each request Privoxy let through. See also debug 1024.<br>
+ debug 1 # Log the destination for each request Privoxy let through.<br>
- debug 2 # show each connection status<br>
+ # See also debug 1024.<br>
+ debug 2 # show each connection status<br>
debug 4 # show I/O status<br>
-
debug 8 # show header parsing<br>
-
debug 128 # debug redirects<br>
debug 256 # debug GIF de-animation<br>
-
debug 512 # Common Log Format<br>
+ debug 1024 # Log the destination for requests Privoxy didn't let through,<br>
- debug 1024 # Log the destination for requests Privoxy didn't let through, and the reason why.<br>
+ # and the reason why.<br>
debug 4096 # Startup banner and warnings.<br>
-
debug 8192 # Non-fatal errors<br>
debug 65536 # Log applying actions</p>
- <p>If you are having trouble with a filter, please additionally
- enable</p>
+ <p>If you are having trouble with a filter, please additionally enable</p>
<p class="LITERALLAYOUT">
- debug 64 # debug regular expression filters</p>If
- you suspect that Privoxy interprets the request or the response
- incorrectly, please enable
+ debug 64 # debug regular expression filters</p>If you suspect
+ that Privoxy interprets the request or the response incorrectly, please enable
<p class="LITERALLAYOUT">
debug 32768 # log all data read from the network</p>
- <p>It's easy for us to ignore log messages that aren't relevant but
- missing log messages may make it impossible to investigate a
- problem. If you aren't sure which of the debug directives are
- relevant, please just enable all of them and let us worry about
- it.</p>
- <p>Note that Privoxy log files may contain sensitive information so
- please don't submit any logfiles you didn't read first. You can
- mask sensitive information as long as it's clear that you removed
- something.</p>
+ <p>It's easy for us to ignore log messages that aren't relevant but missing log messages may make it
+ impossible to investigate a problem. If you aren't sure which of the debug directives are relevant, please
+ just enable all of them and let us worry about it.</p>
+ <p>Note that Privoxy log files may contain sensitive information so please don't submit any logfiles you
+ didn't read first. You can mask sensitive information as long as it's clear that you removed something.</p>
</li>
</ul>
- <p>You don't have to tell us your actual name when filing a problem
- report, but if you don't, please use a nickname so we can differentiate
- between your messages and the ones entered by other "anonymous" users
- that may respond to your request if they have the same problem or
- already found a solution. Note that due to spam the trackers may not
- always allow to post without being logged into SourceForge. If that's
- the case, you are still free to create a login that isn't directly
- linked to your name, though.</p>
- <p>Please also check the status of your request a few days after
- submitting it, as we may request additional information. If you use a
- SF id, you should automatically get a mail when someone responds to
- your request. Please don't bother to add an email address when using
- the tracker. If you prefer to communicate through email, just use one
- of the mailing lists directly.</p>
- <p>If you are new to reporting problems, you might be interested in
- <a href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html" target=
- "_top">How to Report Bugs Effectively</a>.</p>
- <p>The <a href=
- "https://www.privoxy.org/user-manual/appendix.html#ACTIONSANAT" target=
- "_top">appendix of the Privoxy User Manual</a> also has helpful
- information on understanding <tt class="LITERAL">actions</tt>, and
+ <p>You don't have to tell us your actual name when filing a problem report, but if you don't, please use a
+ nickname so we can differentiate between your messages and the ones entered by other "anonymous" users that may
+ respond to your request if they have the same problem or already found a solution. Note that due to spam the
+ trackers may not always allow to post without being logged into SourceForge. If that's the case, you are still
+ free to create a login that isn't directly linked to your name, though.</p>
+ <p>Please also check the status of your request a few days after submitting it, as we may request additional
+ information. If you use a SF id, you should automatically get a mail when someone responds to your request.
+ Please don't bother to add an email address when using the tracker. If you prefer to communicate through email,
+ just use one of the mailing lists directly.</p>
+ <p>If you are new to reporting problems, you might be interested in <a href=
+ "http://www.chiark.greenend.org.uk/~sgtatham/bugs.html" target="_top">How to Report Bugs Effectively</a>.</p>
+ <p>The <a href="https://www.privoxy.org/user-manual/appendix.html#ACTIONSANAT" target="_top">appendix of the
+ Privoxy User Manual</a> also has helpful information on understanding <tt class="LITERAL">actions</tt>, and
<tt class="LITERAL">action</tt> debugging.</p>
</div>
<div class="SECT2">
- <h2 class="SECT2"><a name="CONTACT-SUPPORT" id="CONTACT-SUPPORT">6.2.
- Get Support</a></h2>
+ <h2 class="SECT2"><a name="CONTACT-SUPPORT" id="CONTACT-SUPPORT">6.2. Get Support</a></h2>
<p>All users are welcome to discuss their issues on the <a href=
- "https://lists.privoxy.org/mailman/listinfo/privoxy-users" target=
- "_top">users mailing list</a>, where the developers also hang
- around.</p>
- <p>Please don't send private support requests to individual Privoxy
- developers, either use the mailing lists or the support trackers.</p>
- <p>If you have to contact a Privoxy developer directly for other
- reasons, please send a real mail and do not bother with SourceForge's
- messaging system. Answers to SourceForge messages are usually bounced
- by SourceForge's mail server in which case the developer wasted time
- writing a response you don't get. From your point of view it will look
- like your message has been completely ignored, so this is frustrating
- for all parties involved.</p>
- <p>Note that the Privoxy mailing lists are moderated. Posts from
- unsubscribed addresses have to be accepted manually by a moderator.
- This may cause a delay of several days and if you use a subject that
- doesn't clearly mention Privoxy or one of its features, your message
- may be accidentally discarded as spam.</p>
- <p>If you aren't subscribed, you should therefore spend a few seconds
- to come up with a proper subject. Additionally you should make it clear
- that you want to get CC'd. Otherwise some responses will be directed to
- the mailing list only, and you won't see them.</p>
+ "https://lists.privoxy.org/mailman/listinfo/privoxy-users" target="_top">users mailing list</a>, where the
+ developers also hang around.</p>
+ <p>Please don't send private support requests to individual Privoxy developers, either use the mailing lists or
+ the support trackers.</p>
+ <p>If you have to contact a Privoxy developer directly for other reasons, please send a real mail and do not
+ bother with SourceForge's messaging system. Answers to SourceForge messages are usually bounced by SourceForge's
+ mail server in which case the developer wasted time writing a response you don't get. From your point of view it
+ will look like your message has been completely ignored, so this is frustrating for all parties involved.</p>
+ <p>Note that the Privoxy mailing lists are moderated. Posts from unsubscribed addresses have to be accepted
+ manually by a moderator. This may cause a delay of several days and if you use a subject that doesn't clearly
+ mention Privoxy or one of its features, your message may be accidentally discarded as spam.</p>
+ <p>If you aren't subscribed, you should therefore spend a few seconds to come up with a proper subject.
+ Additionally you should make it clear that you want to get CC'd. Otherwise some responses will be directed to the
+ mailing list only, and you won't see them.</p>
</div>
<div class="SECT2">
- <h2 class="SECT2"><a name="REPORTING" id="REPORTING">6.3. Reporting
- Problems</a></h2>
- <p><span class="QUOTE">"Problems"</span> for our purposes, come in two
- forms:</p>
+ <h2 class="SECT2"><a name="REPORTING" id="REPORTING">6.3. Reporting Problems</a></h2>
+ <p><span class="QUOTE">"Problems"</span> for our purposes, come in two forms:</p>
<ul>
<li>
- <p>Configuration issues, such as ads that slip through, or sites
- that don't function properly due to one <span class=
- "APPLICATION">Privoxy</span> <span class="QUOTE">"action"</span> or
- another being turned <span class="QUOTE">"on"</span>.</p>
+ <p>Configuration issues, such as ads that slip through, or sites that don't function properly due to one
+ <span class="APPLICATION">Privoxy</span> <span class="QUOTE">"action"</span> or another being turned
+ <span class="QUOTE">"on"</span>.</p>
</li>
<li>
- <p><span class="QUOTE">"Bugs"</span> in the programming code that
- makes up <span class="APPLICATION">Privoxy</span>, such as that
- might cause a crash. Documentation issues, for example spelling
+ <p><span class="QUOTE">"Bugs"</span> in the programming code that makes up <span class=
+ "APPLICATION">Privoxy</span>, such as that might cause a crash. Documentation issues, for example spelling
errors and unclear descriptions, are bugs, too.</p>
</li>
</ul>
<div class="SECT3">
- <h3 class="SECT3"><a name="CONTACT-ADS" id="CONTACT-ADS">6.3.1.
- Reporting Ads or Other Configuration Problems</a></h3>
- <p>Please send feedback on ads that slipped through, innocent images
- that were blocked, sites that don't work properly, and other
- configuration related problem of <tt class=
- "FILENAME">default.action</tt> file, to <a href=
- "https://sourceforge.net/tracker/?group_id=11118&atid=460288"
- target=
- "_top">https://sourceforge.net/tracker/?group_id=11118&atid=460288</a>,
- the Actions File Tracker.</p>
+ <h3 class="SECT3"><a name="CONTACT-ADS" id="CONTACT-ADS">6.3.1. Reporting Ads or Other Configuration
+ Problems</a></h3>
+ <p>Please send feedback on ads that slipped through, innocent images that were blocked, sites that don't work
+ properly, and other configuration related problem of <tt class="FILENAME">default.action</tt> file, to <a href=
+ "https://sourceforge.net/tracker/?group_id=11118&atid=460288" target=
+ "_top">https://sourceforge.net/tracker/?group_id=11118&atid=460288</a>, the Actions File Tracker.</p>
</div>
<div class="SECT3">
- <h3 class="SECT3"><a name="CONTACT-BUGS" id="CONTACT-BUGS">6.3.2.
- Reporting Bugs</a></h3>
- <p>Before reporting bugs, please make sure that the bug has
- <span class="emphasis"><i class="EMPHASIS">not already been
- submitted</i></span> and observe the additional hints at the top of
- the <a href=
- "https://sourceforge.net/tracker/?func=add&group_id=11118&atid=111118"
- target="_top">submit form</a>. If already submitted, please feel free
- to add any info to the original report that might help to solve the
+ <h3 class="SECT3"><a name="CONTACT-BUGS" id="CONTACT-BUGS">6.3.2. Reporting Bugs</a></h3>
+ <p>Before reporting bugs, please make sure that the bug has <span class="emphasis"><i class="EMPHASIS">not
+ already been submitted</i></span> and observe the additional hints at the top of the <a href=
+ "https://sourceforge.net/tracker/?func=add&group_id=11118&atid=111118" target="_top">submit form</a>.
+ If already submitted, please feel free to add any info to the original report that might help to solve the
issue.</p>
</div>
</div>
<div class="SECT2">
- <h2 class="SECT2"><a name="SECURITY-CONTACT" id="SECURITY-CONTACT">6.4.
- Reporting security problems</a></h2>
- <p>If you discovered a security problem or merely suspect that a bug
- might be a security issue, please mail Fabian Keil
- <fk@fabiankeil.de> (OpenPGP fingerprint: 4F36 C17F 3816 9136 54A1
- E850 6918 2291 8BA2 371C).</p>
- <p>Usually you should get a response within a day, otherwise it's
- likely that either your mail or the response didn't make it. If that
- happens, please mail to the developer list to request a status
- update.</p>
+ <h2 class="SECT2"><a name="SECURITY-CONTACT" id="SECURITY-CONTACT">6.4. Reporting security problems</a></h2>
+ <p>If you discovered a security problem or merely suspect that a bug might be a security issue, please mail
+ Fabian Keil <fk@fabiankeil.de> (OpenPGP fingerprint: 4F36 C17F 3816 9136 54A1 E850 6918 2291 8BA2
+ 371C).</p>
+ <p>Usually you should get a response within a day, otherwise it's likely that either your mail or the response
+ didn't make it. If that happens, please mail to the developer list to request a status update.</p>
</div>
<div class="SECT2">
- <h2 class="SECT2"><a name="MAILING-LISTS" id="MAILING-LISTS">6.5.
- Mailing Lists</a></h2>
- <p>If you prefer to communicate through email, instead of using a web
- interface, feel free to use one of the mailing lists. To discuss issues
- that haven't been completely diagnosed yet, please use the Privoxy
- users list. Technically interested users and people who wish to
- contribute to the project are always welcome on the developers list.
- You can find an overview of all <span class=
- "APPLICATION">Privoxy</span>-related mailing lists, including list
- archives, at: <a href="https://lists.privoxy.org/mailman/listinfo"
- target="_top">https://lists.privoxy.org/mailman/listinfo</a>. The lists
- hosted on privoxy.org have been created in 2016, the previously-used
- lists hosted at SourceForge are deprecated but the archives may still
- be useful: <a href="https://sourceforge.net/mail/?group_id=11118"
- target="_top">https://sourceforge.net/mail/?group_id=11118</a>.</p>
+ <h2 class="SECT2"><a name="MAILING-LISTS" id="MAILING-LISTS">6.5. Mailing Lists</a></h2>
+ <p>If you prefer to communicate through email, instead of using a web interface, feel free to use one of the
+ mailing lists. To discuss issues that haven't been completely diagnosed yet, please use the Privoxy users list.
+ Technically interested users and people who wish to contribute to the project are always welcome on the
+ developers list. You can find an overview of all <span class="APPLICATION">Privoxy</span>-related mailing lists,
+ including list archives, at: <a href="https://lists.privoxy.org/mailman/listinfo" target=
+ "_top">https://lists.privoxy.org/mailman/listinfo</a>. The lists hosted on privoxy.org have been created in 2016,
+ the previously-used lists hosted at SourceForge are deprecated but the archives may still be useful: <a href=
+ "https://sourceforge.net/mail/?group_id=11118" target=
+ "_top">https://sourceforge.net/mail/?group_id=11118</a>.</p>
</div>
<div class="SECT2">
- <h2 class="SECT2"><a name="SF-TRACKERS" id="SF-TRACKERS">6.6.
- SourceForge support trackers</a></h2>
- <p>The <a href=
- "https://sourceforge.net/tracker/?group_id=11118&atid=211118"
- target="_top">SourceForge support trackers</a> may be used as well, but
- have various technical problems that are unlikely to be fixed anytime
- soon. If you don't get a timely response, please try the mailing list
- as well.</p>
+ <h2 class="SECT2"><a name="SF-TRACKERS" id="SF-TRACKERS">6.6. SourceForge support trackers</a></h2>
+ <p>The <a href="https://sourceforge.net/tracker/?group_id=11118&atid=211118" target="_top">SourceForge
+ support trackers</a> may be used as well, but have various technical problems that are unlikely to be fixed
+ anytime soon. If you don't get a timely response, please try the mailing list as well.</p>
</div>
</div>
<div class="NAVFOOTER">
<hr align="left" width="100%">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
+ <table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
- <td width="33%" align="left" valign="top"><a href="trouble.html"
- accesskey="P">Prev</a></td>
- <td width="34%" align="center" valign="top"><a href="index.html"
- accesskey="H">Home</a></td>
- <td width="33%" align="right" valign="top"><a href="copyright.html"
- accesskey="N">Next</a></td>
+ <td width="33%" align="left" valign="top"><a href="trouble.html" accesskey="P">Prev</a></td>
+ <td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">Home</a></td>
+ <td width="33%" align="right" valign="top"><a href="copyright.html" accesskey="N">Next</a></td>
</tr>
<tr>
<td width="33%" align="left" valign="top">Troubleshooting</td>
<td width="34%" align="center" valign="top"> </td>
- <td width="33%" align="right" valign="top">Privoxy Copyright, License
- and History</td>
+ <td width="33%" align="right" valign="top">Privoxy Copyright, License and History</td>
</tr>
</table>
</div>
<html>
<head>
<title>Privoxy Copyright, License and History</title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
- <link rel="HOME" title="Privoxy Frequently Asked Questions" href=
- "index.html">
- <link rel="PREVIOUS" title=
- "Contacting the developers, Bug Reporting and Feature Requests" href=
- "contact.html">
+ <meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
+ <link rel="HOME" title="Privoxy Frequently Asked Questions" href="index.html">
+ <link rel="PREVIOUS" title="Contacting the developers, Bug Reporting and Feature Requests" href="contact.html">
<link rel="STYLESHEET" type="text/css" href="../p_doc.css">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
-<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
-"#840084" alink="#0000FF">
+<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">
+ <table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
- <th colspan="3" align="center">Privoxy Frequently Asked
- Questions</th>
+ <th colspan="3" align="center">Privoxy Frequently Asked Questions</th>
</tr>
<tr>
- <td width="10%" align="left" valign="bottom"><a href="contact.html"
- accesskey="P">Prev</a></td>
+ <td width="10%" align="left" valign="bottom"><a href="contact.html" accesskey="P">Prev</a></td>
<td width="80%" align="center" valign="bottom"></td>
<td width="10%" align="right" valign="bottom"> </td>
</tr>
<hr align="left" width="100%">
</div>
<div class="SECT1">
- <h1 class="SECT1"><a name="COPYRIGHT" id="COPYRIGHT">7. Privoxy
- Copyright, License and History</a></h1>
- <p>Copyright � 2001-2017 by Privoxy Developers <code class=
- "EMAIL"><<a href=
+ <h1 class="SECT1"><a name="COPYRIGHT" id="COPYRIGHT">7. Privoxy Copyright, License and History</a></h1>
+ <p>Copyright � 2001-2017 by Privoxy Developers <code class="EMAIL"><<a href=
"mailto:privoxy-devel@lists.privoxy.org">privoxy-devel@lists.privoxy.org</a>></code></p>
- <p>Some source code is based on code Copyright � 1997 by Anonymous Coders
- and Junkbusters, Inc. and licensed under the <i class="CITETITLE">GNU
- General Public License</i>.</p>
- <p>Portions of this document are <span class="QUOTE">"borrowed"</span>
- from the original <span class="APPLICATION">Junkbuster</span> (tm) FAQ,
- and modified as appropriate for <span class=
+ <p>Some source code is based on code Copyright � 1997 by Anonymous Coders and Junkbusters, Inc. and licensed under
+ the <i class="CITETITLE">GNU General Public License</i>.</p>
+ <p>Portions of this document are <span class="QUOTE">"borrowed"</span> from the original <span class=
+ "APPLICATION">Junkbuster</span> (tm) FAQ, and modified as appropriate for <span class=
"APPLICATION">Privoxy</span>.</p>
<div class="SECT2">
- <h2 class="SECT2"><a name="AEN1507" id="AEN1507">7.1. License</a></h2>
- <p><span class="APPLICATION">Privoxy</span> is free software; you can
- redistribute it and/or modify it under the terms of the <i class=
- "CITETITLE">GNU General Public License</i>, version 2, as published by
- the Free Software Foundation.</p>
- <p><span class="APPLICATION">Privoxy</span> is distributed in the hope
- that it will be useful, but WITHOUT ANY WARRANTY; without even the
- implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
- PURPOSE. See the <a href=
- "https://www.privoxy.org/user-manual/copyright.html#LICENSE" target=
- "_top"><i class="CITETITLE">license</i></a> for details.</p>
+ <h2 class="SECT2"><a name="AEN1518" id="AEN1518">7.1. License</a></h2>
+ <p><span class="APPLICATION">Privoxy</span> is free software; you can redistribute it and/or modify it under the
+ terms of the <i class="CITETITLE">GNU General Public License</i>, version 2, as published by the Free Software
+ Foundation.</p>
+ <p><span class="APPLICATION">Privoxy</span> is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ <a href="https://www.privoxy.org/user-manual/copyright.html#LICENSE" target="_top"><i class=
+ "CITETITLE">license</i></a> for details.</p>
</div>
<div class="SECT2">
- <h2 class="SECT2"><a name="AEN1516" id="AEN1516">7.2. History</a></h2>
- <p>A long time ago, there was the <span class="APPLICATION">Internet
- Junkbuster</span>, by Anonymous Coders and Junkbusters Corporation.
- This saved many users a lot of pain in the early days of web
- advertising and user tracking.</p>
- <p>But the web, its protocols and standards, and with it, the
- techniques for forcing ads on users, give up autonomy over their
- browsing, and for tracking them, keeps evolving. Unfortunately, the
- <span class="APPLICATION">Internet Junkbuster</span> did not. Version
- 2.0.2, published in 1998, was the last official release, available from
- Junkbusters Corporation. Fortunately, it had been released under the
- GNU <a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html"
- target="_top">GPL</a>, which allowed further development by others.</p>
- <p>So Stefan Waldherr started maintaining an improved version of the
- software, to which eventually a number of people contributed patches.
- It could already replace banners with a transparent image, and had a
- first version of pop-up killing, but it was still very closely based on
- the original, with all its limitations, such as the lack of HTTP/1.1
- support, flexible per-site configuration, or content modification. The
- last release from this effort was version 2.0.2-10, published in
- 2000.</p>
- <p>Then, some <a href=
- "https://www.privoxy.org/user-manual/copyright.html#AUTHORS" target=
- "_top">developers</a> picked up the thread, and started turning the
- software inside out, upside down, and then reassembled it, adding many
- <a href=
- "https://www.privoxy.org/user-manual/introduction.html#FEATURES"
- target="_top">new features</a> along the way.</p>
- <p>The result of this is <span class="APPLICATION">Privoxy</span>,
- whose first stable version, 3.0, was released August, 2002.</p>
- <p>As of 2012 the Junkbusters Corporation's website
- (http://www.junkbusters.com/) has been shut down, but Privoxy is still
- actively maintained.</p>
+ <h2 class="SECT2"><a name="AEN1527" id="AEN1527">7.2. History</a></h2>
+ <p>A long time ago, there was the <span class="APPLICATION">Internet Junkbuster</span>, by Anonymous Coders and
+ Junkbusters Corporation. This saved many users a lot of pain in the early days of web advertising and user
+ tracking.</p>
+ <p>But the web, its protocols and standards, and with it, the techniques for forcing ads on users, give up
+ autonomy over their browsing, and for tracking them, keeps evolving. Unfortunately, the <span class=
+ "APPLICATION">Internet Junkbuster</span> did not. Version 2.0.2, published in 1998, was the last official
+ release, available from Junkbusters Corporation. Fortunately, it had been released under the GNU <a href=
+ "http://www.gnu.org/licenses/old-licenses/gpl-2.0.html" target="_top">GPL</a>, which allowed further development
+ by others.</p>
+ <p>So Stefan Waldherr started maintaining an improved version of the software, to which eventually a number of
+ people contributed patches. It could already replace banners with a transparent image, and had a first version of
+ pop-up killing, but it was still very closely based on the original, with all its limitations, such as the lack
+ of HTTP/1.1 support, flexible per-site configuration, or content modification. The last release from this effort
+ was version 2.0.2-10, published in 2000.</p>
+ <p>Then, some <a href="https://www.privoxy.org/user-manual/copyright.html#AUTHORS" target="_top">developers</a>
+ picked up the thread, and started turning the software inside out, upside down, and then reassembled it, adding
+ many <a href="https://www.privoxy.org/user-manual/introduction.html#FEATURES" target="_top">new features</a>
+ along the way.</p>
+ <p>The result of this is <span class="APPLICATION">Privoxy</span>, whose first stable version, 3.0, was released
+ August, 2002.</p>
+ <p>As of 2012 the Junkbusters Corporation's website (http://www.junkbusters.com/) has been shut down, but Privoxy
+ is still actively maintained.</p>
</div>
</div>
<div class="NAVFOOTER">
<hr align="left" width="100%">
- <table summary="Footer navigation table" width="100%" border="0"
- cellpadding="0" cellspacing="0">
+ <table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
- <td width="33%" align="left" valign="top"><a href="contact.html"
- accesskey="P">Prev</a></td>
- <td width="34%" align="center" valign="top"><a href="index.html"
- accesskey="H">Home</a></td>
+ <td width="33%" align="left" valign="top"><a href="contact.html" accesskey="P">Prev</a></td>
+ <td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">Home</a></td>
<td width="33%" align="right" valign="top"> </td>
</tr>
<tr>
- <td width="33%" align="left" valign="top">Contacting the developers,
- Bug Reporting and Feature Requests</td>
+ <td width="33%" align="left" valign="top">Contacting the developers, Bug Reporting and Feature Requests</td>
<td width="34%" align="center" valign="top"> </td>
<td width="33%" align="right" valign="top"> </td>
</tr>
<html>
<head>
<title>General Information</title>
- <meta name="GENERATOR" content=
- "Modular DocBook HTML Stylesheet Version 1.79">
- <link rel="HOME" title="Privoxy Frequently Asked Questions" href=
- "index.html">
- <link rel="PREVIOUS" title="Privoxy Frequently Asked Questions" href=
- "index.html">
+ <meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
+ <link rel="HOME" title="Privoxy Frequently Asked Questions" href="index.html">
+ <link rel="PREVIOUS" title="Privoxy Frequently Asked Questions" href="index.html">
<link rel="NEXT" title="Installation" href="installation.html">
<link rel="STYLESHEET" type="text/css" href="../p_doc.css">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
-<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
-"#840084" alink="#0000FF">
+<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">
+ <table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
<tr>
- <th colspan="3" align="center">Privoxy Frequently Asked
- Questions</th>
+ <th colspan="3" align="center">Privoxy Frequently Asked Questions</th>
</tr>
<tr>
- <td width="10%" align="left" valign="bottom"><a href="index.html"
- accesskey="P">Prev</a></td>
+ <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=
- "installation.html" accesskey=&
projects / privoxy.git / commitdiff