-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Coding Guidelines</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
CLASS="SECT1"
><A
NAME="CODING"
->4. Coding Guidelines</A
-></H1
+></A
+>4. Coding Guidelines</H1
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="S1"
->4.1. Introduction</A
-></H2
+></A
+>4.1. Introduction</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
CLASS="SECT2"
><A
NAME="S2"
->4.2. Using Comments</A
-></H2
+></A
+>4.2. Using Comments</H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="S3"
->4.2.1. Comment, Comment, Comment</A
-></H3
+></A
+>4.2.1. Comment, Comment, Comment</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S4"
->4.2.2. Use blocks for comments</A
-></H3
+></A
+>4.2.2. Use blocks for comments</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S5"
->4.2.3. Keep Comments on their own line</A
-></H3
+></A
+>4.2.3. Keep Comments on their own line</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S6"
->4.2.4. Comment each logical step</A
-></H3
+></A
+>4.2.4. Comment each logical step</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S7"
->4.2.5. Comment All Functions Thoroughly</A
-></H3
+></A
+>4.2.5. Comment All Functions Thoroughly</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S8"
+></A
>4.2.6. Comment at the end of braces if the
- content is more than one screen length</A
-></H3
+ content is more than one screen length</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT2"
><A
NAME="S9"
->4.3. Naming Conventions</A
-></H2
+></A
+>4.3. Naming Conventions</H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="S10"
->4.3.1. Variable Names</A
-></H3
+></A
+>4.3.1. Variable Names</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S11"
->4.3.2. Function Names</A
-></H3
+></A
+>4.3.2. Function Names</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S12"
->4.3.3. Header file prototypes</A
-></H3
+></A
+>4.3.3. Header file prototypes</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S13"
->4.3.4. Enumerations, and #defines</A
-></H3
+></A
+>4.3.4. Enumerations, and #defines</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S14"
->4.3.5. Constants</A
-></H3
+></A
+>4.3.5. Constants</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT2"
><A
NAME="S15"
->4.4. Using Space</A
-></H2
+></A
+>4.4. Using Space</H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="S16"
->4.4.1. Put braces on a line by themselves.</A
-></H3
+></A
+>4.4.1. Put braces on a line by themselves.</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S17"
+></A
>4.4.2. ALL control statements should have a
- block</A
-></H3
+ block</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S18"
+></A
>4.4.3. Do not belabor/blow-up boolean
- expressions</A
-></H3
+ expressions</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S19"
+></A
>4.4.4. Use white space freely because it is
- free</A
-></H3
+ free</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S20"
+></A
>4.4.5. Don't use white space around structure
- operators</A
-></H3
+ operators</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S21"
+></A
>4.4.6. Make the last brace of a function stand
- out</A
-></H3
+ out</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S22"
->4.4.7. Use 3 character indentions</A
-></H3
+></A
+>4.4.7. Use 3 character indentions</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT2"
><A
NAME="S23"
->4.5. Initializing</A
-></H2
+></A
+>4.5. Initializing</H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="S24"
->4.5.1. Initialize all variables</A
-></H3
+></A
+>4.5.1. Initialize all variables</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT2"
><A
NAME="S25"
->4.6. Functions</A
-></H2
+></A
+>4.6. Functions</H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="S26"
+></A
>4.6.1. Name functions that return a boolean as a
- question.</A
-></H3
+ question.</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S27"
+></A
>4.6.2. Always specify a return type for a
- function.</A
-></H3
+ function.</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S28"
+></A
>4.6.3. Minimize function calls when iterating by
- using variables</A
-></H3
+ using variables</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S29"
->4.6.4. Pass and Return by Const Reference</A
-></H3
+></A
+>4.6.4. Pass and Return by Const Reference</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S30"
->4.6.5. Pass and Return by Value</A
-></H3
+></A
+>4.6.5. Pass and Return by Value</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S31"
->4.6.6. Names of include files</A
-></H3
+></A
+>4.6.6. Names of include files</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S32"
+></A
>4.6.7. Provide multiple inclusion
- protection</A
-></H3
+ protection</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S33"
->4.6.8. Use `extern "C"` when appropriate</A
-></H3
+></A
+>4.6.8. Use `extern "C"` when appropriate</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S34"
+></A
>4.6.9. Where Possible, Use Forward Struct
- Declaration Instead of Includes</A
-></H3
+ Declaration Instead of Includes</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT2"
><A
NAME="S35"
->4.7. General Coding Practices</A
-></H2
+></A
+>4.7. General Coding Practices</H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="S36"
->4.7.1. Turn on warnings</A
-></H3
+></A
+>4.7.1. Turn on warnings</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S37"
+></A
>4.7.2. Provide a default case for all switch
- statements</A
-></H3
+ statements</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S38"
+></A
>4.7.3. Try to avoid falling through cases in a
- switch statement.</A
-></H3
+ switch statement.</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S39"
+></A
>4.7.4. Use 'long' or 'short' Instead of
- 'int'</A
-></H3
+ 'int'</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S40"
->4.7.5. Don't mix size_t and other types</A
-></H3
+></A
+>4.7.5. Don't mix size_t and other types</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S41"
+></A
>4.7.6. Declare each variable and struct on its
- own line.</A
-></H3
+ own line.</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S42"
->4.7.7. Use malloc/zalloc sparingly</A
-></H3
+></A
+>4.7.7. Use malloc/zalloc sparingly</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S43"
+></A
>4.7.8. The Programmer Who Uses 'malloc' is
- Responsible for Ensuring 'free'</A
-></H3
+ Responsible for Ensuring 'free'</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S44"
+></A
>4.7.9. Add loaders to the `file_list' structure
- and in order</A
-></H3
+ and in order</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="S45"
+></A
>4.7.10. "Uncertain" new code and/or changes to
- existing code, use FIXME</A
-></H3
+ existing code, use FIXME</H3
><P
><SPAN
CLASS="emphasis"
CLASS="SECT2"
><A
NAME="S46"
+></A
>4.8. Addendum: Template for files and function
- comment blocks:</A
-></H2
+ comment blocks:</H2
><P
><SPAN
CLASS="emphasis"
><TD
><PRE
CLASS="PROGRAMLISTING"
->const char FILENAME_rcs[] = "$Id: coding.html,v 1.19.2.7 2004/01/31 00:05:44 oes Exp $";
+>const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.7 2006/07/18 14:48:50 david__schmidt Exp $";
/*********************************************************************
*
- * File : $Source: /cvsroot/ijbswa/current/doc/webserver/developer-manual/coding.html,v $
+ * File : $Source$
*
* Purpose : (Fill me in with a good description!)
*
* Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*
* Revisions :
- * $Log: coding.html,v $
- * Revision 1.19.2.7 2004/01/31 00:05:44 oes
- * Regenerated from sgml source
- *
+ * $Log$
*
*********************************************************************/
CLASS="PROGRAMLISTING"
>#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: coding.html,v 1.19.2.7 2004/01/31 00:05:44 oes Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.7 2006/07/18 14:48:50 david__schmidt Exp $"
/*********************************************************************
*
- * File : $Source: /cvsroot/ijbswa/current/doc/webserver/developer-manual/coding.html,v $
+ * File : $Source$
*
* Purpose : (Fill me in with a good description!)
*
* Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*
* Revisions :
- * $Log: coding.html,v $
- * Revision 1.19.2.7 2004/01/31 00:05:44 oes
- * Regenerated from sgml source
- *
+ * $Log$
*
*********************************************************************/
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Contacting the developers, Bug Reporting and Feature Requests</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
CLASS="SECT1"
><A
NAME="CONTACT"
->8. Contacting the developers, Bug Reporting and Feature Requests</A
-></H1
+></A
+>8. Contacting the developers, Bug Reporting and Feature Requests</H1
><P
> We value your feedback. In fact, we rely on it to improve
<SPAN
CLASS="SECT2"
><A
NAME="CONTACT-SUPPORT"
->8.1. Get Support</A
-></H2
+></A
+>8.1. Get Support</H2
><P
> For casual users, our
<A
CLASS="SECT2"
><A
NAME="CONTACT-BUGS"
->8.2. Report Bugs</A
-></H2
+></A
+>8.2. Report Bugs</H2
><P
> Please report all bugs <SPAN
CLASS="emphasis"
CLASS="SECT2"
><A
NAME="CONTACT-FEATURE"
->8.3. Request New Features</A
-></H2
+></A
+>8.3. Request New Features</H2
><P
> You are welcome to submit ideas on new features or other proposals
for improvement through our feature request tracker at
CLASS="SECT2"
><A
NAME="CONTACT-ADS"
->8.4. Report Ads or Other Actions-Related Problems</A
-></H2
+></A
+>8.4. Report Ads or Other Actions-Related Problems</H2
><P
> Please send feedback on ads that slipped through, innocent images that were blocked,
and any other problems relating to the <TT
CLASS="SECT2"
><A
NAME="CONTACT-OTHER"
->8.5. Other</A
-></H2
+></A
+>8.5. Other</H2
><P
>For any other issues, feel free to use the mailing lists. Technically interested users
and people who wish to contribute to the project are also welcome on the developers list!
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Privoxy Copyright, License and History</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
CLASS="SECT1"
><A
NAME="COPYRIGHT"
->9. Privoxy Copyright, License and History</A
-></H1
+></A
+>9. Privoxy Copyright, License and History</H1
><P
-> Copyright © 2001 - 2004 by Privoxy Developers <CODE
+> Copyright © 2001 - 2004 by Privoxy Developers <TT
CLASS="EMAIL"
><<A
HREF="mailto:developers@privoxy.org"
>developers@privoxy.org</A
->></CODE
+>></TT
></P
><P
> Some source code is based on code Copyright © 1997 by Anonymous Coders
><H2
CLASS="SECT2"
><A
-NAME="AEN1177"
->9.1. License</A
-></H2
+NAME="AEN1161"
+></A
+>9.1. License</H2
><P
> <SPAN
CLASS="APPLICATION"
><H2
CLASS="SECT2"
><A
-NAME="AEN1193"
->9.2. History</A
-></H2
+NAME="AEN1177"
+></A
+>9.2. History</H2
><P
> In the beginning, there was the
<A
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>The CVS Repository</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
CLASS="SECT1"
><A
NAME="CVS"
->2. The CVS Repository</A
-></H1
+></A
+>2. The CVS Repository</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
CLASS="SECT2"
><A
NAME="CVSACCESS"
->2.1. Access to CVS</A
-></H2
+></A
+>2.1. Access to CVS</H2
><P
> The project's CVS repository is hosted on
<A
documentation</A
> for the technical access details for your
operating system. For historical reasons, the CVS server is
- called <VAR
+ called <TT
CLASS="LITERAL"
->cvs.ijbswa.sourceforge.net</VAR
+>ijbswa.cvs.sourceforge.net</TT
>, the repository is
- called <VAR
+ called <TT
CLASS="LITERAL"
->ijbswa</VAR
+>ijbswa</TT
>, and the source tree module is called
- <VAR
+ <TT
CLASS="LITERAL"
->current</VAR
+>current</TT
>.
</P
></DIV
CLASS="SECT2"
><A
NAME="CVSBRANCHES"
->2.2. Branches</A
-></H2
+></A
+>2.2. Branches</H2
><P
> Within the CVS repository, there are modules and branches. As
- mentioned, the sources are in the <VAR
+ mentioned, the sources are in the <TT
CLASS="LITERAL"
->current</VAR
+>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://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/"
+HREF="http://ijbswa.cvs.sourceforge.net/ijbswa/"
TARGET="_top"
->http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/</A
+>http://ijbswa.cvs.sourceforge.net/ijbswa/</A
>,
which might help with visualizing how these pieces fit together.
</P
><P
> Branches are used to fork a sub-development path from the main trunk.
- Within the <VAR
+ Within the <TT
CLASS="LITERAL"
->current</VAR
+>current</TT
> module where the sources are, there
is always at least one <SPAN
CLASS="QUOTE"
versioning.)
</P
><P
-> This will result in at least two active branches, which means there may
- be occasions that require the same (or similar) item to be
- checked into to two different places (assuming its a bugfix and needs
- fixing in both the stable and unstable trees). This also means that in
- order to have access to both trees, both will have to be checked out
- separately. Use the <VAR
-CLASS="LITERAL"
->cvs -r</VAR
-> flag to check out a
- branch, e.g: <VAR
-CLASS="LITERAL"
->cvs co -r v_3_0_branch current</VAR
->.
+> 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
+ brances.
</P
></DIV
><DIV
CLASS="SECT2"
><A
NAME="CVSCOMMIT"
->2.3. CVS Commit Guidelines</A
-></H2
+></A
+>2.3. CVS Commit Guidelines</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
><UL
><LI
><P
-> Never (read: <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->never, ever</I
-></SPAN
->) be tempted to commit
- that small change without testing it thoroughly first. When we're
+> 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
></LI
></UL
->
- </P
-><P
-> Stable branches are handled with more care, especially after the
- initial *.*.0 release, and we are just in bugfix mode. In addition to
- the above, the below applies only to the stable branch (currently the
- <VAR
-CLASS="LITERAL"
->v_3_0_branch</VAR
-> branch):
- </P
-><P
-> <P
-></P
-><UL
-><LI
-><P
-> Do not commit <SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->anything</I
-></SPAN
-> unless your proposed
- changes have been well tested first, preferably by other members of the
- project, or have prior approval of the project leaders or consensus
- of the devel list.
- </P
-></LI
-><LI
-><P
-> Where possible, bugfixes and changes should be tested in the main
- development trunk first. There may be occasions where this is not
- feasible, though.
- </P
-></LI
-><LI
-><P
-> Alternately, proposed changes can be submitted as patches to the patch tracker on
- Sourceforge first: <A
-HREF="http://sourceforge.net/tracker/?group_id=11118&atid=311118"
-TARGET="_top"
->http://sourceforge.net/tracker/?group_id=11118&atid=311118</A
->.
- Then ask for peer review.
- </P
-></LI
-><LI
-><P
-> Do not even think about anything except bugfixes. No new features!
- </P
-></LI
-></UL
>
</P
></DIV
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Documentation Guidelines</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
CLASS="SECT1"
><A
NAME="DOCUMENTATION"
->3. Documentation Guidelines</A
-></H1
+></A
+>3. Documentation Guidelines</H1
><P
> All formal documents are maintained in Docbook SGML and located in the
- <SAMP
+ <TT
CLASS="COMPUTEROUTPUT"
->doc/source/*</SAMP
+>doc/source/*</TT
> directory. You will need
<A
HREF="http://www.docbook.org"
>, <I
CLASS="CITETITLE"
>AUTHORS</I
->
+>,
+ <I
+CLASS="CITETITLE"
+>INSTALL</I
+>,
<I
CLASS="CITETITLE"
>privoxy.1</I
>DO NOT edit these directly</I
></SPAN
>. Edit the SGML source, or
- contact someone involved in the documentation (at present Hal).
+ contact someone involved in the documentation.
</P
><P
> <TT
> Other, less formal documents (e.g. <TT
CLASS="FILENAME"
>LICENSE</TT
->,
- <TT
-CLASS="FILENAME"
->INSTALL</TT
->) are maintained as plain text files in the
- top-level source directory. At least for the time being.
+>) 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 now being kept in CVS under
+ CVS. HTML versions are also being kept in CVS under
<TT
CLASS="FILENAME"
>doc/webserver/*</TT
+>. And PDF version are kept in
+ <TT
+CLASS="FILENAME"
+>doc/pdf/*</TT
>.
</P
><P
> Formal documents are built with the Makefile targets of
- <SAMP
+ <TT
CLASS="COMPUTEROUTPUT"
->make dok</SAMP
+>make dok</TT
>, or alternately
- <SAMP
+ <TT
CLASS="COMPUTEROUTPUT"
->make redhat-dok</SAMP
+>make redhat-dok</TT
>. If you have problems,
try both. The build process uses the document SGML sources in
- <SAMP
+ <TT
CLASS="COMPUTEROUTPUT"
->doc/source/*/*</SAMP
+>doc/source/*/*</TT
> to update all text files in
- <SAMP
+ <TT
CLASS="COMPUTEROUTPUT"
->doc/text/</SAMP
+>doc/text/</TT
> and to update all HTML
- documents in <SAMP
+ documents in <TT
CLASS="COMPUTEROUTPUT"
->doc/webserver/</SAMP
+>doc/webserver/</TT
>.
</P
><P
TYPE="1"
><LI
><P
-> First, build the docs by running <SAMP
+> First, build the docs by running <TT
CLASS="COMPUTEROUTPUT"
>make
- dok</SAMP
-> (or alternately <SAMP
+ dok</TT
+> (or alternately <TT
CLASS="COMPUTEROUTPUT"
>make
- redhat-dok</SAMP
->). For PDF docs, do <SAMP
+ redhat-dok</TT
+>). For PDF docs, do <TT
CLASS="COMPUTEROUTPUT"
>make
- dok-pdf</SAMP
+ dok-pdf</TT
>.
</P
></LI
><LI
><P
-> Run <SAMP
+> Run <TT
CLASS="COMPUTEROUTPUT"
->make webserver</SAMP
+>make webserver</TT
> which copies all
- files from <SAMP
+ files from <TT
CLASS="COMPUTEROUTPUT"
->doc/webserver</SAMP
+>doc/webserver</TT
> to the
sourceforge webserver via scp.
</P
CLASS="EMPHASIS"
>after</I
></SPAN
-> the <VAR
+> the <TT
CLASS="LITERAL"
->$VERSION</VAR
+>$VERSION</TT
> and
other release specific data in <TT
CLASS="FILENAME"
CLASS="SECT2"
><A
NAME="SGML"
->3.1. Quickstart to Docbook and SGML</A
-></H2
+></A
+>3.1. Quickstart to Docbook and SGML</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
CLASS="QUOTE"
>"closed"</SPAN
>. If not, you
- will likely generate errors. Example: <VAR
+ will likely generate errors. Example: <TT
CLASS="LITERAL"
><title>My
- Title</title></VAR
+ Title</title></TT
>. They are also case-insensitive, but we
strongly suggest using all lower case. This keeps compatibility with
[Docbook] <SPAN
CLASS="QUOTE"
>"sections"</SPAN
> for the most part. Sections
- will be processed into HTML headers (e.g. <VAR
+ will be processed into HTML headers (e.g. <TT
CLASS="LITERAL"
->h1</VAR
+>h1</TT
> for
- <VAR
+ <TT
CLASS="LITERAL"
->sect1</VAR
+>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 <VAR
+ TOC's are set to a depth of three. Meaning <TT
CLASS="LITERAL"
->sect1</VAR
+>sect1</TT
>,
- <VAR
+ <TT
CLASS="LITERAL"
->sect2</VAR
->, and <VAR
+>sect2</TT
+>, and <TT
CLASS="LITERAL"
->sect3</VAR
+>sect3</TT
> will have TOC
- entries, but <VAR
+ entries, but <TT
CLASS="LITERAL"
->sect4</VAR
+>sect4</TT
> will not. Each section requires
- a <VAR
+ a <TT
CLASS="LITERAL"
-><title></VAR
+><title></TT
> element, and at least one
- <VAR
+ <TT
CLASS="LITERAL"
-><para></VAR
+><para></TT
>. There is a limit of five section
levels in Docbook, but generally three should be sufficient for our
purposes.</P
><literallayout></literallayout></I
></SPAN
>, like
- <VAR
+ <TT
CLASS="LITERAL"
-><pre></VAR
+><pre></TT
>, more or less.
</TD
></TR
><screen></screen></I
></SPAN
>, screen output, implies
- <VAR
+ <TT
CLASS="LITERAL"
-><literallayout></VAR
+><literallayout></TT
>.
</TD
></TR
><ulink url="example.com"></ulink></I
></SPAN
>, like
- HTML <VAR
+ HTML <TT
CLASS="LITERAL"
-><a></VAR
+><a></TT
> tag.
</TD
></TR
CLASS="SECT2"
><A
NAME="DOCSTYLE"
+></A
>3.2. <SPAN
CLASS="APPLICATION"
>Privoxy</SPAN
-> Documentation Style</A
-></H2
+> Documentation Style</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
><LI
><P
> Our documents are available in differing formats. Right now, they
- are just plain text, TML, and PDF, but others are always a
+ are just plain text, HTML, and PDF, but others are always a
future possibility. Be careful with URLs (<ulink>), and avoid
this mistake:
</P
CLASS="APPLICATION"
>aspell</SPAN
> can check SGML with the
- <VAR
+ <TT
CLASS="LITERAL"
->-H</VAR
+>-H</TT
> option. (<SPAN
CLASS="APPLICATION"
>ispell</SPAN
><H2
CLASS="SECT2"
><A
-NAME="AEN233"
->3.3. Privoxy Custom Entities</A
-></H2
+NAME="AEN217"
+></A
+>3.3. Privoxy Custom Entities</H2
><P
> <SPAN
CLASS="APPLICATION"
>"internal entities"</SPAN
>. These are like variables in
programming. Well, sort of. For instance, we have the
- <VAR
+ <TT
CLASS="LITERAL"
->p-version</VAR
+>p-version</TT
> entity that contains the current
<SPAN
CLASS="APPLICATION"
> text entities are defined like:
</P
><P
-> <VAR
+> <TT
CLASS="LITERAL"
-><!entity supported SYSTEM "supported.sgml"></VAR
+><!entity supported SYSTEM "supported.sgml"></TT
>
</P
><P
>supported.sgml</TT
> is available for inclusion anywhere
in the doc. To make this happen, just reference the now defined
- entity: <VAR
+ entity: <TT
CLASS="LITERAL"
->&supported;</VAR
+>&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.
>
version string, e.g. <SPAN
CLASS="QUOTE"
->"3.0.3"</SPAN
+>"3.0.4"</SPAN
>.
</TD
></TR
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Privoxy Developer Manual</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
REL="NEXT"
TITLE="Introduction"
HREF="introduction.html"><LINK
CLASS="TITLE"
><A
NAME="AEN2"
->Privoxy Developer Manual</A
-></H1
+></A
+>Privoxy Developer Manual</H1
><P
CLASS="PUBDATE"
> <SUB
<BR></P
><P
CLASS="PUBDATE"
->$Id: index.html,v 1.19.2.7 2004/01/31 00:05:44 oes Exp $<BR></P
+>$Id: developer-manual.sgml,v 2.7 2006/07/18 14:48:50 david__schmidt Exp $<BR></P
><DIV
><DIV
CLASS="ABSTRACT"
-><P
-></P
><A
NAME="AEN9"
></A
><P
+></P
+><P
> The developer manual provides guidance on coding, testing, packaging, documentation
and other issues of importance to those involved with
<SPAN
for anyone who wants to join the team.</P
><P
> Please note that this document is constantly evolving. This copy represents
- the state at the release of version 3.0.3.
+ the state at the release of version 3.0.4.
You can find the latest version of the this manual at <A
HREF="http://www.privoxy.org/developer-manual/"
TARGET="_top"
></DT
><DT
>3.3. <A
-HREF="documentation.html#AEN233"
+HREF="documentation.html#AEN217"
>Privoxy Custom Entities</A
></DT
></DL
><DL
><DT
>9.1. <A
-HREF="copyright.html#AEN1177"
+HREF="copyright.html#AEN1161"
>License</A
></DT
><DT
>9.2. <A
-HREF="copyright.html#AEN1193"
+HREF="copyright.html#AEN1177"
>History</A
></DT
></DL
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Introduction</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
CLASS="SECT1"
><A
NAME="INTRODUCTION"
->1. Introduction</A
-></H1
+></A
+>1. Introduction</H1
><P
> <SPAN
CLASS="APPLICATION"
CLASS="SECT2"
><A
NAME="QUICKSTART"
->1.1. Quickstart to Privoxy Development</A
-></H2
+></A
+>1.1. Quickstart to Privoxy Development</H2
><P
> The first step is to join the <A
-HREF="mailto:developers@privoxy.org"
+HREF="mailto:ijbswa-developers@lists.sourceforge.net"
TARGET="_top"
>developer's mailing list</A
>.
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Releasing a New Version</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
CLASS="SECT1"
><A
NAME="NEWRELEASE"
->6. Releasing a New Version</A
-></H1
+></A
+>6. Releasing a New Version</H1
><P
> When we release versions of <SPAN
CLASS="APPLICATION"
CLASS="SECT2"
><A
NAME="VERSIONNUMBERS"
->6.1. Version numbers</A
-></H2
+></A
+>6.1. Version numbers</H2
><P
> First you need to determine which version number the release will have.
<SPAN
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 <VAR
+ version reported as <TT
CLASS="LITERAL"
->0.0.0</VAR
+>0.0.0</TT
>, during that period
between releases when changes are being added. This is to denote
that this code is <SPAN
></SPAN
>. Then
as the release nears, the version is bumped according: e.g.
- <VAR
+ <TT
CLASS="LITERAL"
->3.0.1 -> 0.0.0 -> 3.0.2</VAR
+>3.0.1 -> 0.0.0 -> 3.0.2</TT
>.
</P
></LI
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
- <VAR
+ <TT
CLASS="LITERAL"
->3.0</VAR
+>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
>and</I
></SPAN
> the stable release branch,
- which is <VAR
+ which is <TT
CLASS="LITERAL"
->v_3_0_branch</VAR
+>v_3_0_branch</TT
> at the moment).
</P
></DIV
CLASS="SECT2"
><A
NAME="BEFORERELEASE"
->6.2. Before the Release: Freeze</A
-></H2
+></A
+>6.2. Before the Release: Freeze</H2
><P
> The following <SPAN
CLASS="emphasis"
>
link from the main page since we need to keep manuals for various
versions available). The CGI pages will link to something like
- <VAR
+ <TT
CLASS="LITERAL"
->http://privoxy.org/$(VERSION)/user-manual/</VAR
+>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.
CLASS="SECT2"
><A
NAME="THERELEASE"
->6.3. Building and Releasing the Packages</A
-></H2
+></A
+>6.3. Building and Releasing the Packages</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.
CLASS="SECT3"
><A
NAME="PACK-GUIDELINES"
->6.3.1. Note on Privoxy Packaging</A
-></H3
+></A
+>6.3.1. Note on Privoxy Packaging</H3
><P
> Please keep these general guidelines in mind when putting together
your package. These apply to <SPAN
CLASS="SECT3"
><A
NAME="NEWRELEASE-TARBALL"
->6.3.2. Source Tarball</A
-></H3
+></A
+>6.3.2. Source Tarball</H3
><P
> First, <SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="NEWRELEASE-RPM"
->6.3.3. SuSE, Conectiva or Red Hat RPM</A
-></H3
+></A
+>6.3.3. SuSE, Conectiva or Red Hat RPM</H3
><P
-> In following text, replace <VAR
+> In following text, replace <TT
CLASS="REPLACEABLE"
->dist</VAR
+><I
+>dist</I
+></TT
>
with either <SPAN
CLASS="QUOTE"
now examine the file <TT
CLASS="FILENAME"
>privoxy-</TT
-><VAR
+><TT
CLASS="REPLACEABLE"
->dist</VAR
+><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
- <VAR
+ <TT
CLASS="REPLACEABLE"
->dist</VAR
+><I
+>dist</I
+></TT
> which is built from version
X.Y.Z. Check the
<A
><TD
><PRE
CLASS="PROGRAMLISTING"
-> make <VAR
+> make <TT
CLASS="REPLACEABLE"
->dist</VAR
+><I
+>dist</I
+></TT
>-dist</PRE
></TD
></TR
><TD
><PRE
CLASS="PROGRAMLISTING"
-> make <VAR
+> make <TT
CLASS="REPLACEABLE"
->dist</VAR
->-upload <VAR
+><I
+>dist</I
+></TT
+>-upload <TT
CLASS="REPLACEABLE"
->rpm_packagerev</VAR
+><I
+>rpm_packagerev</I
+></TT
></PRE
></TD
></TR
>
</P
><P
-> where <VAR
+> where <TT
CLASS="REPLACEABLE"
->rpm_packagerev</VAR
+><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.
CLASS="SECT3"
><A
NAME="NEWRELEASE-OS2"
->6.3.4. OS/2</A
-></H3
+></A
+>6.3.4. OS/2</H3
><P
> First, <SPAN
CLASS="emphasis"
><TD
><PRE
CLASS="PROGRAMLISTING"
-> cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup</PRE
+> cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup</PRE
></TD
></TR
></TABLE
CLASS="SECT3"
><A
NAME="NEWRELEASE-SOLARIS"
->6.3.5. Solaris</A
-></H3
+></A
+>6.3.5. Solaris</H3
><P
> Login to Sourceforge's compilefarm via ssh:
</P
CLASS="SECT3"
><A
NAME="NEWRELEASE-WINDOWS"
->6.3.6. Windows</A
-></H3
+></A
+>6.3.6. Windows</H3
><P
> You should ensure you have the latest version of Cygwin (from
<A
><TD
><PRE
CLASS="PROGRAMLISTING"
-> cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup</PRE
+> cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup</PRE
></TD
></TR
></TABLE
CLASS="SECT3"
><A
NAME="NEWRELEASE-DEBIAN"
->6.3.7. Debian</A
-></H3
+></A
+>6.3.7. Debian</H3
><P
> First, <SPAN
CLASS="emphasis"
><TD
><PRE
CLASS="PROGRAMLISTING"
-> debchange -v 3.0.3-stable-1 "New upstream version"</PRE
+> debchange -v 3.0.4-BETA-1 "New upstream version"</PRE
></TD
></TR
></TABLE
> This will create
<TT
CLASS="FILENAME"
->../privoxy_3.0.3-stable-1_i386.deb</TT
+>../privoxy_3.0.4-BETA-1_i386.deb</TT
>
which can be uploaded. To upload the package to Sourceforge, simply
issue
CLASS="SECT3"
><A
NAME="NEWRELEASE-MACOSX"
->6.3.8. Mac OSX</A
-></H3
+></A
+>6.3.8. Mac OSX</H3
><P
> First, <SPAN
CLASS="emphasis"
><TD
><PRE
CLASS="PROGRAMLISTING"
-> cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup</PRE
+> cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup</PRE
></TD
></TR
></TABLE
CLASS="SECT3"
><A
NAME="NEWRELEASE-FREEBSD"
->6.3.9. FreeBSD</A
-></H3
+></A
+>6.3.9. FreeBSD</H3
><P
> Login to Sourceforge's compile-farm via ssh:
</P
CLASS="SECT3"
><A
NAME="NEWRELEASE-HPUX"
->6.3.10. HP-UX 11</A
-></H3
+></A
+>6.3.10. HP-UX 11</H3
><P
> First, <SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="NEWRELEASE-AMIGA"
->6.3.11. Amiga OS</A
-></H3
+></A
+>6.3.11. Amiga OS</H3
><P
> First, <SPAN
CLASS="emphasis"
CLASS="SECT3"
><A
NAME="NEWRELEASE-AIX"
->6.3.12. AIX</A
-></H3
+></A
+>6.3.12. AIX</H3
><P
> Login to Sourceforge's compilefarm via ssh:
</P
CLASS="SECT2"
><A
NAME="RELEASING"
->6.4. Uploading and Releasing Your Package</A
-></H2
+></A
+>6.4. Uploading and Releasing Your Package</H2
><P
> After the package is ready, it is time to upload it
to SourceForge, and go through the release steps. The upload
></LI
><LI
><P
-> user: <VAR
+> user: <TT
CLASS="LITERAL"
->anonymous</VAR
+>anonymous</TT
>
</P
></LI
><LI
><P
-> password: <VAR
+> password: <TT
CLASS="LITERAL"
->ijbswa-developers@lists.sourceforge.net</VAR
+>ijbswa-developers@lists.sourceforge.net</TT
>
</P
></LI
>http://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 <VAR
+ second column, and click <TT
CLASS="LITERAL"
->Add Release</VAR
+>Add Release</TT
>. You will
then need to create a new release for your package, using the format
- of <VAR
+ of <TT
CLASS="LITERAL"
->$VERSION ($CODE_STATUS)</VAR
+>$VERSION ($CODE_STATUS)</TT
>, e.g. <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
->3.0.3
+>3.0.4
(beta)</I
></SPAN
>.
</P
><P
> If you have made errors, or need to make changes, you can go through
- essentially the same steps, but select <VAR
+ essentially the same steps, but select <TT
CLASS="LITERAL"
->Edit Release</VAR
+>Edit Release</TT
>,
- instead of <VAR
+ instead of <TT
CLASS="LITERAL"
->Add Release</VAR
+>Add Release</TT
>.
</P
></DIV
CLASS="SECT2"
><A
NAME="AFTERRELEASE"
->6.5. After the Release</A
-></H2
+></A
+>6.5. After the Release</H2
><P
> When all (or: most of the) packages have been uploaded and made available,
send an email to the <A
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>See also</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
CLASS="SECT1"
><A
NAME="SEEALSO"
->10. See also</A
-></H1
+></A
+>10. See also</H1
><P
> Other references and sites of interest to <SPAN
CLASS="APPLICATION"
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Testing Guidelines</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
CLASS="SECT1"
><A
NAME="TESTING"
->5. Testing Guidelines</A
-></H1
+></A
+>5. Testing Guidelines</H1
><P
>To be filled.</P
><DIV
CLASS="SECT2"
><A
NAME="TESTING-PLAN"
->5.1. Testplan for releases</A
-></H2
+></A
+>5.1. Testplan for releases</H2
><P
> Explain release numbers. major, minor. developer releases. etc.
CLASS="SECT2"
><A
NAME="TESTING-REPORT"
->5.2. Test reports</A
-></H2
+></A
+>5.2. Test reports</H2
><P
>Please submit test reports only with the <A
HREF="http://sourceforge.net/tracker/?func=add&group_id=11118&atid=395005"
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Update the Webserver</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
+"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
CLASS="SECT1"
><A
NAME="WEBSERVER-UPDATE"
->7. Update the Webserver</A
-></H1
+></A
+>7. Update the Webserver</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,
projects / privoxy.git / commitdiff