From: hal9 Date: Tue, 22 Aug 2006 23:36:11 +0000 (+0000) Subject: HTML developer manual. X-Git-Tag: v_3_0_5~147 X-Git-Url: http://www.privoxy.org/gitweb/misc.html?a=commitdiff_plain;h=1c1ffceac284f70345a662ea6e2ddad08007b749;p=privoxy.git HTML developer manual. --- diff --git a/doc/webserver/developer-manual/coding.html b/doc/webserver/developer-manual/coding.html index fead798d..7fcad1bf 100644 --- a/doc/webserver/developer-manual/coding.html +++ b/doc/webserver/developer-manual/coding.html @@ -1,11 +1,11 @@ - Coding Guidelines4. Coding Guidelines4. Coding Guidelines

4.1. Introduction

4.1. Introduction

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 @@ -105,16 +105,16 @@ CLASS="SECT2" CLASS="SECT2" >4.2. Using Comments4.2. Using Comments

4.2.1. Comment, Comment, Comment

4.2.1. Comment, Comment, Comment

4.2.2. Use blocks for comments4.2.2. Use blocks for comments

4.2.3. Keep Comments on their own line4.2.3. Keep Comments on their own line

4.2.4. Comment each logical step4.2.4. Comment each logical step

4.2.5. Comment All Functions Thoroughly4.2.5. Comment All Functions Thoroughly

4.2.6. Comment at the end of braces if the - content is more than one screen length

4.3. Naming Conventions4.3. Naming Conventions

4.3.1. Variable Names

4.3.1. Variable Names

4.3.2. Function Names4.3.2. Function Names

4.3.3. Header file prototypes4.3.3. Header file prototypes

4.3.4. Enumerations, and #defines4.3.4. Enumerations, and #defines

4.3.5. Constants4.3.5. Constants

4.4. Using Space4.4. Using Space

4.4.1. Put braces on a line by themselves.

4.4.1. Put braces on a line by themselves.

4.4.2. ALL control statements should have a - block

4.4.3. Do not belabor/blow-up boolean - expressions

4.4.4. Use white space freely because it is - free

4.4.5. Don't use white space around structure - operators

4.4.6. Make the last brace of a function stand - out

4.4.7. Use 3 character indentions4.4.7. Use 3 character indentions

4.5. Initializing4.5. Initializing

4.5.1. Initialize all variables

4.5.1. Initialize all variables

4.6. Functions4.6. Functions

4.6.1. Name functions that return a boolean as a - question.

4.6.2. Always specify a return type for a - function.

4.6.3. Minimize function calls when iterating by - using variables

4.6.4. Pass and Return by Const Reference4.6.4. Pass and Return by Const Reference

4.6.5. Pass and Return by Value4.6.5. Pass and Return by Value

4.6.6. Names of include files4.6.6. Names of include files

4.6.7. Provide multiple inclusion - protection

4.6.8. Use `extern "C"` when appropriate4.6.8. Use `extern "C"` when appropriate

4.6.9. Where Possible, Use Forward Struct - Declaration Instead of Includes

4.7. General Coding Practices4.7. General Coding Practices

4.7.1. Turn on warnings

4.7.1. Turn on warnings

4.7.2. Provide a default case for all switch - statements

4.7.3. Try to avoid falling through cases in a - switch statement.

4.7.4. Use 'long' or 'short' Instead of - 'int'

4.7.5. Don't mix size_t and other types4.7.5. Don't mix size_t and other types

4.7.6. Declare each variable and struct on its - own line.

4.7.7. Use malloc/zalloc sparingly4.7.7. Use malloc/zalloc sparingly

4.7.8. The Programmer Who Uses 'malloc' is - Responsible for Ensuring 'free'

4.7.9. Add loaders to the `file_list' structure - and in order

4.7.10. "Uncertain" new code and/or changes to - existing code, use FIXME

4.8. Addendum: Template for files and function - comment blocks:

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!)
  *
@@ -2367,10 +2367,7 @@ CLASS="PROGRAMLISTING"
  *                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$
  *
  *********************************************************************/
 
@@ -2424,10 +2421,10 @@ WIDTH="100%"
 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!)
  *
@@ -2457,10 +2454,7 @@ CLASS="PROGRAMLISTING"
  *                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$
  *
  *********************************************************************/
 
diff --git a/doc/webserver/developer-manual/contact.html b/doc/webserver/developer-manual/contact.html
index 31383e67..c6d655d0 100644
--- a/doc/webserver/developer-manual/contact.html
+++ b/doc/webserver/developer-manual/contact.html
@@ -1,11 +1,11 @@
-
 Contacting the developers, Bug Reporting and Feature Requests8. Contacting the developers, Bug Reporting and Feature Requests8. Contacting the developers, Bug Reporting and Feature Requests
 We value your feedback. In fact, we rely on it to improve
  8.1. Get Support8.1. Get Support
 For casual users, our 
  8.2. Report Bugs8.2. Report Bugs
 Please report all bugs 8.3. Request New Features8.3. Request New Features
 You are welcome to submit ideas on new features or other proposals
  for improvement through our feature request tracker at
@@ -201,8 +201,8 @@ CLASS="SECT2"
 CLASS="SECT2"
 >8.4. Report Ads or Other Actions-Related Problems8.4. Report Ads or Other Actions-Related Problems
 Please send feedback on ads that slipped through, innocent images that were blocked,
  and any other problems relating to the 8.5. Other8.5. Other
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!
diff --git a/doc/webserver/developer-manual/copyright.html b/doc/webserver/developer-manual/copyright.html
index aae28830..8fe9f30d 100644
--- a/doc/webserver/developer-manual/copyright.html
+++ b/doc/webserver/developer-manual/copyright.html
@@ -1,11 +1,11 @@
-
 Privoxy Copyright, License and History9. Privoxy Copyright, License and History9. Privoxy Copyright, License and History
 Copyright © 2001 - 2004 by Privoxy Developers  Copyright © 2001 - 2004 by Privoxy Developers 
 Some source code is based on code Copyright © 1997 by Anonymous Coders
@@ -96,9 +96,9 @@ CLASS="SECT2"
 >
9.1. License
9.1. License
 
9.2. History
9.2. History
 In the beginning, there was the
  
 The CVS Repository2. The CVS Repository2. The CVS Repository
      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 
@@ -88,8 +88,8 @@ CLASS="SECT2"
 CLASS="SECT2"
 >2.1. Access to CVS2.1. Access to CVS
        The project's CVS repository is hosted on
          for the technical access details for your
         operating system. For historical reasons, the CVS server is
-        called cvs.ijbswa.sourceforge.netijbswa.cvs.sourceforge.net, the repository is
-        called ijbswaijbswa, and the source tree module is called
-        currentcurrent.
2.2. Branches2.2. Branches

Within the CVS repository, there are modules and branches. As - mentioned, the sources are in the currentcurrent "module". Other modules are present for platform specific issues. There is a webview of the CVS hierarchy at http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/http://ijbswa.cvs.sourceforge.net/ijbswa/, which might help with visualizing how these pieces fit together.

Branches are used to fork a sub-development path from the main trunk. - Within the currentcurrent module where the sources are, there is always at least one

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 cvs -r flag to check out a - branch, e.g: cvs co -r v_3_0_branch current. +> 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.

2.3. CVS Commit Guidelines2.3. CVS Commit Guidelines

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 @@ -212,14 +203,8 @@ NAME="CVSCOMMIT" >

  • Never (read: never, ever) 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.

-

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 - v_3_0_branch branch): -

  • Do not commit anything 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. -

  • Where possible, bugfixes and changes should be tested in the main - development trunk first. There may be occasions where this is not - feasible, though. -

  • Alternately, proposed changes can be submitted as patches to the patch tracker on - Sourceforge first: http://sourceforge.net/tracker/?group_id=11118&atid=311118. - Then ask for peer review. -

  • Do not even think about anything except bugfixes. No new features! -

Documentation Guidelines3. Documentation Guidelines3. Documentation Guidelines

All formal documents are maintained in Docbook SGML and located in the - doc/source/*doc/source/* directory. You will need , AUTHORS +>, + INSTALL, privoxy.1DO NOT edit these directly. Edit the SGML source, or - contact someone involved in the documentation (at present Hal). + contact someone involved in the documentation.

Other, less formal documents (e.g. LICENSE, - INSTALL) 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.

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 doc/webserver/*. And PDF version are kept in + doc/pdf/*.

Formal documents are built with the Makefile targets of - make dokmake dok, or alternately - make redhat-dokmake redhat-dok. If you have problems, try both. The build process uses the document SGML sources in - doc/source/*/*doc/source/*/* to update all text files in - doc/text/doc/text/ and to update all HTML - documents in doc/webserver/doc/webserver/.

  • First, build the docs by running First, build the docs by running make - dok (or alternately (or alternately make - redhat-dok). For PDF docs, do ). For PDF docs, do make - dok-pdf.

  • Run Run make webservermake webserver which copies all - files from doc/webserverdoc/webserver to the sourceforge webserver via scp.

    after the the $VERSION$VERSION and other release specific data in 3.1. Quickstart to Docbook and SGML3.1. Quickstart to Docbook and SGML

    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 @@ -333,10 +337,10 @@ CLASS="QUOTE" CLASS="QUOTE" >"closed". If not, you - will likely generate errors. Example: <title>My - Title</title>. They are also case-insensitive, but we strongly suggest using all lower case. This keeps compatibility with [Docbook] "sections" for the most part. Sections - will be processed into HTML headers (e.g. h1h1 for - sect1sect1). The Docbook 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 sect1sect1, - sect2, and sect2, and sect3sect3 will have TOC - entries, but sect4sect4 will not. Each section requires - a <title><title> element, and at least one - <para><para>. There is a limit of five section levels in Docbook, but generally three should be sufficient for our purposes.

    <literallayout></literallayout>, like - <pre><pre>, more or less. <screen></screen>, screen output, implies - <literallayout><literallayout>. <ulink url="example.com"></ulink>, like - HTML <a><a> tag. 3.2. Privoxy Documentation Style Documentation Style

    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 @@ -640,7 +644,7 @@ CLASS="LITERALLAYOUT" >

  • 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:

    aspell can check SGML with the - -H-H option. (ispell

    3.3. Privoxy Custom Entities

    3.3. Privoxy Custom Entities

    "internal entities". These are like variables in programming. Well, sort of. For instance, we have the - p-versionp-version entity that contains the current text entities are defined like:

    <!entity supported SYSTEM "supported.sgml"><!entity supported SYSTEM "supported.sgml">

    supported.sgml is available for inclusion anywhere in the doc. To make this happen, just reference the now defined - entity: &supported;&supported; (starts with an ampersand and ends with a semi-colon), and the contents will be dumped into the finished doc at that point. @@ -795,7 +799,7 @@ CLASS="APPLICATION" > version string, e.g. "3.0.3""3.0.4". Privoxy Developer ManualPrivoxy Developer ManualPrivoxy Developer Manual

    $Id: index.html,v 1.19.2.7 2004/01/31 00:05:44 oes Exp $

    $Id: developer-manual.sgml,v 2.7 2006/07/18 14:48:50 david__schmidt Exp $

    The developer manual provides guidance on coding, testing, packaging, documentation and other issues of importance to those involved with

    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

    3.3. Privoxy Custom Entities
    9.1. License
    9.2. History
    Introduction1. Introduction1. Introduction

    1.1. Quickstart to Privoxy Development1.1. Quickstart to Privoxy Development

    The first step is to join the developer's mailing list. diff --git a/doc/webserver/developer-manual/newrelease.html b/doc/webserver/developer-manual/newrelease.html index a9c3b3e7..70df23b7 100644 --- a/doc/webserver/developer-manual/newrelease.html +++ b/doc/webserver/developer-manual/newrelease.html @@ -1,11 +1,11 @@ - Releasing a New Version6. Releasing a New Version6. Releasing a New Version

    When we release versions of 6.1. Version numbers6.1. Version numbers

    First you need to determine which version number the release will have. 0.0.00.0.0, during that period between releases when changes are being added. This is to denote that this code is . Then as the release nears, the version is bumped according: e.g. - 3.0.1 -> 0.0.0 -> 3.0.23.0.1 -> 0.0.0 -> 3.0.2.

    • 3.03.0, 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 @@ -232,9 +232,9 @@ CLASS="EMPHASIS" >and the stable release branch, - which is v_3_0_branchv_3_0_branch at the moment).

    6.2. Before the Release: Freeze6.2. Before the Release: Freeze

    The following link from the main page since we need to keep manuals for various versions available). The CGI pages will link to something like - http://privoxy.org/$(VERSION)/user-manual/http://privoxy.org/$(VERSION)/user-manual/. 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. @@ -429,8 +429,8 @@ CLASS="SECT2" CLASS="SECT2" >6.3. Building and Releasing the Packages6.3. Building and Releasing the Packages

    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. @@ -494,8 +494,8 @@ CLASS="SECT3" CLASS="SECT3" >6.3.1. Note on Privoxy Packaging6.3.1. Note on Privoxy Packaging

    Please keep these general guidelines in mind when putting together your package. These apply to 6.3.2. Source Tarball6.3.2. Source Tarball

    First, 6.3.3. SuSE, Conectiva or Red Hat RPM6.3.3. SuSE, Conectiva or Red Hat RPM

    In following text, replace In following text, replace distdist with either privoxy-distdist.specdistdist which is built from version X.Y.Z. Check the 

      make   make distdist-dist
      make   make dist-upload dist-upload rpm_packagerevrpm_packagerev

    where where rpm_packagerevrpm_packagerev is the RPM release number as determined above. Go to the displayed URL and release the file publicly on Sourceforge. @@ -956,8 +970,8 @@ CLASS="SECT3" CLASS="SECT3" >6.3.4. OS/26.3.4. OS/2

    First, 

      cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co os2setup
    cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co os2setup6.3.5. Solaris6.3.5. Solaris

    Login to Sourceforge's compilefarm via ssh:

    6.3.6. Windows6.3.6. Windows

    You should ensure you have the latest version of Cygwin (from 

      cvs -z3  -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co winsetup
    cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co winsetup6.3.7. Debian6.3.7. Debian

    First, 

      debchange -v 3.0.3-stable-1 "New upstream version"
    debchange -v 3.0.4-BETA-1 "New upstream version" This will create ../privoxy_3.0.3-stable-1_i386.deb../privoxy_3.0.4-BETA-1_i386.deb which can be uploaded. To upload the package to Sourceforge, simply issue @@ -1338,8 +1352,8 @@ CLASS="SECT3" CLASS="SECT3" >6.3.8. Mac OSX6.3.8. Mac OSX

    First, 

      cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa co osxsetup
    cvs -z3 -d:pserver:anonymous@ijbswa.cvs.sourceforge.net:/cvsroot/ijbswa co osxsetup6.3.9. FreeBSD6.3.9. FreeBSD

    Login to Sourceforge's compile-farm via ssh:

    6.3.10. HP-UX 116.3.10. HP-UX 11

    First, 6.3.11. Amiga OS6.3.11. Amiga OS

    First, 6.3.12. AIX6.3.12. AIX

    Login to Sourceforge's compilefarm via ssh:

    6.4. Uploading and Releasing Your Package6.4. Uploading and Releasing Your Package

    After the package is ready, it is time to upload it to SourceForge, and go through the release steps. The upload @@ -1713,17 +1727,17 @@ TARGET="_top" >

  • user: user: anonymousanonymous

  • password: password: ijbswa-developers@lists.sourceforge.netijbswa-developers@lists.sourceforge.net

    • http://sourceforge.net/project/admin/editpackages.php?group_id=11118, making sure you are logged in. Find your target platform in the - second column, and click Add ReleaseAdd Release. You will then need to create a new release for your package, using the format - of $VERSION ($CODE_STATUS)$VERSION ($CODE_STATUS), e.g. 3.0.3 +>3.0.4 (beta). @@ -1786,13 +1800,13 @@ CLASS="QUOTE"

    If you have made errors, or need to make changes, you can go through - essentially the same steps, but select Edit ReleaseEdit Release, - instead of Add ReleaseAdd Release.

    6.5. After the Release6.5. After the Release

    When all (or: most of the) packages have been uploaded and made available, send an email to the See also10. See also10. See also

    Other references and sites of interest to Testing Guidelines5. Testing Guidelines5. Testing Guidelines

    To be filled.

    5.1. Testplan for releases5.1. Testplan for releases

    Explain release numbers. major, minor. developer releases. etc. @@ -159,8 +159,8 @@ CLASS="SECT2" CLASS="SECT2" >5.2. Test reports5.2. Test reports

    Please submit test reports only with the Update the Webserver7. Update the Webserver7. Update the Webserver

    The webserver should be updated at least with each stable release. When updating, please follow these steps to make sure that no broken links,