From c26c4ab4f34425f50fc8b840ba57ec3c3813be1e Mon Sep 17 00:00:00 2001 From: oes Date: Tue, 6 Aug 2002 09:26:41 +0000 Subject: [PATCH] Generated --- doc/webserver/developer-manual/coding.html | 563 +++++------------- doc/webserver/developer-manual/contact.html | 46 +- doc/webserver/developer-manual/copyright.html | 25 +- doc/webserver/developer-manual/cvs.html | 41 +- .../developer-manual/documentation.html | 172 ++---- doc/webserver/developer-manual/index.html | 19 +- .../developer-manual/introduction.html | 18 +- .../developer-manual/newrelease.html | 183 +++--- doc/webserver/developer-manual/seealso.html | 12 +- doc/webserver/developer-manual/testing.html | 22 +- .../developer-manual/webserver-update.html | 19 +- doc/webserver/faq/configuration.html | 20 +- doc/webserver/faq/copyright.html | 7 +- doc/webserver/faq/general.html | 5 +- doc/webserver/faq/index.html | 60 +- doc/webserver/faq/installation.html | 82 ++- doc/webserver/faq/misc.html | 18 +- doc/webserver/faq/trouble.html | 34 +- doc/webserver/user-manual/actions-file.html | 18 +- doc/webserver/user-manual/appendix.html | 22 +- doc/webserver/user-manual/config.html | 129 ++-- doc/webserver/user-manual/configuration.html | 6 +- doc/webserver/user-manual/contact.html | 4 +- doc/webserver/user-manual/copyright.html | 11 +- doc/webserver/user-manual/filter-file.html | 6 +- doc/webserver/user-manual/index.html | 40 +- doc/webserver/user-manual/installation.html | 86 ++- doc/webserver/user-manual/introduction.html | 10 +- doc/webserver/user-manual/quickstart.html | 6 +- doc/webserver/user-manual/seealso.html | 4 +- doc/webserver/user-manual/startup.html | 64 +- doc/webserver/user-manual/templates.html | 4 +- doc/webserver/user-manual/upgradersnote.html | 4 +- 33 files changed, 816 insertions(+), 944 deletions(-) diff --git a/doc/webserver/developer-manual/coding.html b/doc/webserver/developer-manual/coding.html index 8b48122c..43471c68 100644 --- a/doc/webserver/developer-manual/coding.html +++ b/doc/webserver/developer-manual/coding.html @@ -4,8 +4,7 @@ >Coding Guidelines
Prev

4. Coding Guidelines

4. 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 @@ -100,20 +100,21 @@ CLASS="SECT2" >

4.2. Using Comments

4.2. Using Comments

4.2.1. Comment, Comment, Comment

4.2.1. Comment, Comment, Comment

Explanation:

Comment as much as possible without commenting the obvious. @@ -129,12 +130,9 @@ CLASS="EMPHASIS" If the comment describes something different than what the code is doing then maybe a programming error is occurring.

Example:

Next

4.2.2. Use blocks for comments

4.2.2. Use blocks for comments

Explanation:

Comments can help or they can clutter. They help when they @@ -184,12 +181,9 @@ CLASS="EMPHASIS" and the code. Block identifiers do, by surrounding the code with a clear, definable pattern.

Example:

Exception:

If you are trying to add a small logic comment and do not @@ -240,14 +231,13 @@ CLASS="SECT3" >

4.2.3. Keep Comments on their own line

4.2.3. Keep Comments on their own line

Explanation:

It goes back to the question of readability. If the comment @@ -259,12 +249,9 @@ CLASS="EMPHASIS" at the end of closing braces, when used to comment parameters.

Example:

4.2.4. Comment each logical step

4.2.4. Comment each logical step

Explanation:

Logical steps should be commented to help others follow the @@ -344,14 +330,13 @@ CLASS="SECT3" >

4.2.5. Comment All Functions Thoroughly

4.2.5. Comment All Functions Thoroughly

Explanation:

A reader of the code should be able to look at the comments @@ -372,15 +357,14 @@ CLASS="SECT3" >

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

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

Explanation:

Each closing brace should be followed on the same line by a @@ -395,12 +379,9 @@ CLASS="EMPHASIS" >use following a closing brace: } /* -END- if() or while () or etc... */

Example:

4.3. Naming Conventions

4.3. Naming Conventions

4.3.1. Variable Names

4.3.1. Variable Names

Explanation:

Use all lowercase, and separate words via an underscore @@ -456,12 +438,9 @@ CLASS="EMPHASIS" template, class, true, false, ...). This is in case we ever decide to port Privoxy to C++.

Example:

Instead of:

4.3.2. Function Names

4.3.2. Function Names

Explanation:

Use all lowercase, and separate words via an underscore @@ -520,12 +495,9 @@ CLASS="EMPHASIS" template, class, true, false, ...). This is in case we ever decide to port Privoxy to C++.

Example:

Instead of:

4.3.3. Header file prototypes

4.3.3. Header file prototypes

Explanation:

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.

Example:

Instead of:

4.3.4. Enumerations, and #defines

4.3.4. Enumerations, and #defines

Explanation:

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.)

Example:

Note: 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.

Example:

4.3.5. Constants

4.3.5. Constants

Explanation:

Spell common words out entirely (do not remove vowels).

Use underscore (_) to separate adjacent acronyms and abbreviations. Never terminate a name with an underscore.

Example:

Instead of:

4.4. Using Space

4.4. Using Space

4.4.1. Put braces on a line by themselves.

4.4.1. Put braces on a line by themselves.

Explanation:

The brace needs to be on a line all by itself, not at the @@ -797,12 +743,9 @@ CLASS="EMPHASIS" easier to identify the opening and closing braces for a block.

Example:

Instead of:

if ( this == that ) { ... }

if ( this == that ) { ... }

Note: 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.

Status: developer-discretion.

Example exception:

4.4.2. ALL control statements should have a - block

4.4.2. ALL control statements should have a + block

Explanation:

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.

Example:

Instead of:

if ( this == that ) DoSomething(); DoSomethingElse();

if ( this == that ) DoSomething();

Note: 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 @@ -955,15 +876,14 @@ CLASS="SECT3" >

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

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

Example:

Instead of:

if ( condition ) { structure->flag = 1; } else { structure->flag = 0; }

Note: 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 @@ -1005,26 +919,22 @@ CLASS="SECT3" >

4.4.4. Use white space freely because it is - free

4.4.4. Use white space freely because it is + free

Explanation:

Make it readable. The notable exception to using white space freely is listed in the next guideline.

Example:

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

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

Explanation:

- structure pointer operator ( "->" ) - member operator ( @@ -1070,12 +979,9 @@ CLASS="EMPHASIS" connection between the object and variable/function name is not as clear.

Example:

Instead of: aStruct -> aMember; aStruct . aMember; FunctionName ();

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

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

Example:

Instead of:

int function1( ... ) { ...code... return( retCode ); } int function2( ... ) { }

Note: 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 @@ -1164,12 +1060,9 @@ CLASS="EMPHASIS" "do" loops, and long if {} statements too. After all whitespace is free!

Status: developer-discretion on the number of blank lines. Enforced is the end of function comments.

4.4.7. Use 3 character indentions

4.4.7. Use 3 character indentions

Explanation:

If some use 8 character TABs and some use 3 character TABs, @@ -1193,12 +1085,9 @@ CLASS="EMPHASIS" only. If you like to use TABs, pass your code through a filter such as "expand -t3" before checking in your code.

Example:

4.5. Initializing

4.5. Initializing

4.5.1. Initialize all variables

4.5.1. Initialize all variables

Explanation:

Do not assume that the variables declared will not be used @@ -1259,12 +1149,9 @@ CLASS="EMPHASIS" the code. Remove the chance of accidentally using an unassigned variable.

Example:

Note: It is much easier to debug a SIGSEGV if the message says you are trying to access memory address 00000000 and not 129FA012; or arrayPtr[20] causes a SIGSEV vs. arrayPtr[0].

Status: developer-discretion if and only if the variable is assigned a value "shortly after" declaration.

4.6. Functions

4.6. Functions

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

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

Explanation:

Value should be phrased as a question that would logically be answered as a true or false statement

Example:

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

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

Explanation:

The default return for a function is an int. To avoid @@ -1375,26 +1253,22 @@ CLASS="SECT3" >

4.6.3. Minimize function calls when iterating by - using variables

4.6.3. Minimize function calls when iterating by + using variables

Explanation:

It is easy to write the following code, and a clear argument can be made that the code is easy to understand:

Example:

Note: 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 @@ -1432,12 +1303,9 @@ CLASS="EMPHASIS" assign the value to a variable, and evaluate using the variable.

Example:

Exceptions: if the value of blockListLength() *may* change or could *potentially* change, then you must code the function call in the for/while loop.

4.6.4. Pass and Return by Const Reference

4.6.4. Pass and Return by Const Reference

Explanation:

This allows a developer to define a const pointer and call @@ -1500,14 +1364,13 @@ CLASS="SECT3" >

4.6.5. Pass and Return by Value

4.6.5. Pass and Return by Value

Explanation:

Most structures cannot fit onto a normal stack entry (i.e. @@ -1523,14 +1386,13 @@ CLASS="SECT3" >

4.6.6. Names of include files

4.6.6. Names of include files

Explanation:

Your include statements should contain the file name without @@ -1540,12 +1402,9 @@ CLASS="EMPHASIS" partial path to distinguish their header files from system or other header files.

Example:

Exception:

Note: Please! do not add "-I." to the Makefile without a _very_ good reason. This duplicates the #include "file.h" behavior.

4.6.7. Provide multiple inclusion - protection

4.6.7. Provide multiple inclusion + protection

Explanation:

Prevents compiler and linker errors resulting from @@ -1618,12 +1470,9 @@ CLASS="EMPHASIS" with your file name, with "." Changed to "_", and make it uppercase.

Example:

4.6.8. Use `extern "C"` when appropriate

4.6.8. Use `extern "C"` when appropriate

Explanation:

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.

Example:

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

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

Explanation:

Useful in headers that include pointers to other struct's. Modifications to excess header files may cause needless compiles.

Example:

Note: 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.

Status: Use with discretion.

4.7. General Coding Practices

4.7. General Coding Practices

4.7.1. Turn on warnings

4.7.1. Turn on warnings

Explanation

Compiler warnings are meant to help you find bugs. You @@ -1783,15 +1619,14 @@ CLASS="SECT3" >

4.7.2. Provide a default case for all switch - statements

4.7.2. Provide a default case for all switch + statements

Explanation:

What you think is guaranteed is never really guaranteed. The @@ -1799,12 +1634,9 @@ CLASS="EMPHASIS" someday will be passed. So, to protect yourself from the unknown, always have a default step in a switch statement.

Example:

Note: 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.

Another Note: 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 ABEND condition.

Status: Programmer discretion is advised.

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

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

Explanation:

In general, you will want to have a 'break' statement within @@ -1901,26 +1723,22 @@ CLASS="SECT3" >

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

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

Explanation:

On 32-bit platforms, int usually has the range of long. On 16-bit platforms, int has the range of short.

Status: open-to-debate. In the case of most FSF projects (including X/GNU-Emacs), there are typedefs to int4, int8, int16, (or equivalence ... I forget the exact typedefs @@ -1932,14 +1750,13 @@ CLASS="SECT3" >

4.7.5. Don't mix size_t and other types

4.7.5. Don't mix size_t and other types

Explanation:

The type of size_t varies across platforms. Do not make @@ -1954,26 +1771,22 @@ CLASS="SECT3" >

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

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

Explanation:

It can be tempting to declare a series of variables all on one line. Don't.

Example:

Instead of:

long a, b, c;

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

Exceptions: when you want to declare a bunch of loop variables or other trivial variables; feel free to declare them on 1 line. You should, although, provide a good comment on their functions.

Status: developer-discretion.

4.7.7. Use malloc/zalloc sparingly

4.7.7. Use malloc/zalloc sparingly

Explanation:

Create a local struct (on the stack) if the variable will @@ -2052,12 +1852,9 @@ CLASS="EMPHASIS" >Only "malloc" a struct (on the heap) if the variable's life will extend beyond the context of one function call.

Example:

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

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

Explanation:

If you have to "malloc" an instance, you are responsible for @@ -2097,12 +1893,9 @@ CLASS="EMPHASIS" "good thing (tm)". You may need to offer a free/unload/destructor type function to accommodate this.

Example:

Exceptions:

The developer cannot be expected to provide `free'ing functions for C run-time library functions ... such as `strdup'.

Status: developer-discretion. The "main" use of this standard is for allocating and freeing data structures (complex or nested).

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

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

Explanation:

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.

Note: 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 @@ -2176,15 +1959,14 @@ CLASS="SECT3" >

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

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

Explanation:

If you have enough confidence in new code or confidence in @@ -2205,12 +1987,9 @@ CLASS="EMPHASIS" >/* FIXME: new code that *may* break something else... */ ...new code here...

Note: 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 @@ -2222,15 +2001,14 @@ CLASS="SECT2" >

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

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

Example for file comments:

Note: This declares the rcs variables that should be added to the "show-proxy-args" page. If this is a brand new creation by you, you are free to change the "Copyright" section to represent the rights you wish to maintain.

Note: 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.

Example for file header comments:

Example for function comments:

Note: If we all follow this practice, we should be able to parse our code to create a "self-documenting" web page.

PrevContacting the developers, Bug Reporting and Feature Requests
HomeNext
Prev

8. Contacting the developers, Bug Reporting and Feature Requests

8. Contacting the developers, Bug Reporting and Feature Requests

We value your feedback. In fact, we rely on it to improve

8.1. Get Support

8.1. Get Support

For casual users, our support forum at

8.2. Report Bugs

8.2. Report Bugs

Please report all bugs Please report all bugs only through our bug tracker:

8.3. Request New Features

8.3. Request New Features

You are welcome to submit ideas on new features or other proposals for improvement through our feature request tracker at @@ -192,7 +193,9 @@ CLASS="SECT2" >

8.4. Report Ads or Other Actions-Related Problems

8.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 ijbswa-announce - list and available from our files section of + our project page

8.5. Other

8.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! @@ -249,7 +259,6 @@ CLASS="NAVFOOTER" >

Next
PrevPrivoxy Copyright, License and History
HomeNext
Prev

9. Privoxy Copyright, License and History

9. Privoxy Copyright, License and History

Copyright © 2001, 2002 by Privoxy Developers

Next
HomeNext

Next
HomeNext

Next
<para></para>, paragraph delimiter. Most text needs to be within paragraph elements (there are some exceptions).
<emphasis></emphasis>, the stylesheets make this italics.
<filename></filename>, files and directories.
<command></command>, command examples.
<literallayout></literallayout>, like
<itemizedlist></itemizedlist>, list with bullets.
<listitem></listitem>, member of the above.
<screen></screen>, screen output, implies
<ulink url="example.com"></ulink>, like HTML
<quote></quote>, for, doh, quoting text.
p-version: the Privoxy version string, e.g. "2.9.15""2.9.18".
p-status: the project status, either
p-not-stable: use to conditionally include text in
p-stable: just the opposite.
p-text: this doc is only generated as text.
HomeNext

Next
HomeNext

Next
  debchange -v 2.9.15-beta-1 "New upstream version"
debchange -v 2.9.18-beta-1 "New upstream version"