X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=681cd197cb635b64646c96fd37223ac7b7236f53;hp=fbbd67851181f4dec286f9867efbfe04976cd320;hb=f1e040bf5515bc8c762c1c83243fe461afbc4bed;hpb=74602637391ac4c89938bc4b70c1609a34ffe4ac diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index fbbd6785..681cd197 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -8,10 +8,10 @@ - - - - + + + + @@ -23,9 +23,9 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: developer-manual.sgml,v 2.7 2006/07/18 14:48:50 david__schmidt Exp $ + $Id: developer-manual.sgml,v 2.14 2008/01/17 01:49:51 hal9 Exp $ - Copyright (C) 2001, 2002 Privoxy Developers + Copyright (C) 2001-2008 Privoxy Developers http://www.privoxy.org/ See LICENSE. ======================================================================== @@ -44,13 +44,13 @@ - Copyright &my-copy; 2001, 2002 by - Privoxy Developers + Copyright &my-copy; 2001-2007 by + Privoxy Developers - $Id: developer-manual.sgml,v 2.7 2006/07/18 14:48:50 david__schmidt Exp $ + $Id: developer-manual.sgml,v 2.14 2008/01/17 01:49:51 hal9 Exp $ @@ -119,16 +120,17 @@ Hal. --> Privoxy, as an heir to - Junkbuster, is an Open Source project - and licensed under the GPL. As such, Privoxy - 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 Privoxy, and + Junkbuster, is a Free Software project + and the code is licensed under the GPL. As such, + Privoxy 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 Privoxy, and to make it available to as wide an audience as possible. One does not have to be a programmer to contribute. Packaging, testing, - and porting, are all important jobs as well. + documenting and porting, are all important jobs as well. @@ -503,7 +505,7 @@ Hal. You might also find Writing Documentation + url="http://opensource.bureau-cornavin.com/crash-course/index.html">Writing Documentation Using DocBook - A Crash Course useful. @@ -731,8 +733,8 @@ Hal. Explanation: Comment as much as possible without commenting the obvious. - For example do not comment "aVariable is equal to bVariable". - Instead explain why aVariable should be equal to the bVariable. + 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 @@ -746,13 +748,13 @@ Hal. Example: /* if page size greater than 1k ... */ -if ( PageLength() > 1024 ) +if ( page_length() > 1024 ) { ... "block" the page up ... } /* if page size is small, send it in blocks */ -if ( PageLength() > 1024 ) +if ( page_length() > 1024 ) { ... "block" the page up ... } @@ -780,22 +782,22 @@ is actually being done. /********************************************************************* * This will stand out clearly in your code! *********************************************************************/ -if ( thisVariable == thatVariable ) +if ( this_variable == that_variable ) { - DoSomethingVeryImportant(); + do_something_very_important(); } /* unfortunately, this may not */ -if ( thisVariable == thatVariable ) +if ( this_variable == that_variable ) { - DoSomethingVeryImportant(); + do_something_very_important(); } -if ( thisVariable == thatVariable ) /* this may not either */ +if ( this_variable == that_variable ) /* this may not either */ { - DoSomethingVeryImportant(); + do_something_very_important(); } Exception: @@ -827,14 +829,14 @@ if ( thisVariable == thatVariable ) /* this may not either */ * This will stand out clearly in your code, * But the second example won't. *********************************************************************/ -if ( thisVariable == thatVariable ) +if ( this_variable == this_variable ) { - DoSomethingVeryImportant(); + do_something_very_important(); } -if ( thisVariable == thatVariable ) /*can you see me?*/ +if ( this_variable == this_variable ) /*can you see me?*/ { - DoSomethingVeryImportant(); /*not easily*/ + do_something_very_important(); /*not easily*/ } @@ -846,17 +848,17 @@ int urls_rejected = 0; /* # of urls rejected */ if ( 1 == X ) { - DoSomethingVeryImportant(); + do_something_very_important(); } -short DoSomethingVeryImportant( +short do_something_very_important( short firstparam, /* represents something */ short nextparam /* represents something else */ ) { ...code here... -} /* -END- DoSomethingVeryImportant */ +} /* -END- do_something_very_important */ @@ -923,7 +925,7 @@ short DoSomethingVeryImportant( if ( 1 == X ) { - DoSomethingVeryImportant(); + do_something_very_important(); ...some long list of commands... } /* -END- if x is 1 */ @@ -931,7 +933,7 @@ or: if ( 1 == X ) { - DoSomethingVeryImportant(); + do_something_very_important(); ...some long list of commands... } /* -END- if ( 1 == X ) */ @@ -1148,17 +1150,17 @@ while ( more lines are read ) if ( this == that ) { - DoSomething(); - DoSomethingElse(); + do_something(); + do_something_else(); } Instead of: - if ( this == that ) DoSomething(); DoSomethingElse(); + if ( this == that ) do_something(); do_something_else(); or - if ( this == that ) DoSomething(); + if ( this == that ) do_something(); Note: The first example in "Instead of" will execute in a manner other than that which the developer desired (per @@ -1201,14 +1203,14 @@ structure->flag = ( condition ); Example: -int firstValue = 0; -int someValue = 0; -int anotherValue = 0; -int thisVariable = 0; +int first_value = 0; +int some_value = 0; +int another_value = 0; +int this_variable = 0; -if ( thisVariable == thatVariable ) +if ( this_variable == this_variable ) -firstValue = oldValue + ( ( someValue - anotherValue ) - whatever ) +first_value = old_value + ( ( some_value - another_value ) - whatever ) @@ -1228,12 +1230,12 @@ firstValue = oldValue + ( ( someValue - anotherValue ) - whatever ) Example: -aStruct->aMember; -aStruct.aMember; -FunctionName(); +a_struct->a_member; +a_struct.a_member; +function_name(); - Instead of: aStruct -> aMember; aStruct . aMember; - FunctionName (); + Instead of: a_struct -> a_member; a_struct . a_member; + function_name (); @@ -1247,7 +1249,7 @@ FunctionName(); int function1( ... ) { ...code... - return( retCode ); + return( ret_code ); } /* -END- function1 */ @@ -1259,7 +1261,7 @@ int function2( ... ) Instead of: - int function1( ... ) { ...code... return( retCode ); } int + int function1( ... ) { ...code... return( ret_code ); } int function2( ... ) { } Note: Use 1 blank line before the closing brace and 2 @@ -1329,14 +1331,14 @@ int function1( ... ) Example: -short anShort = 0; -float aFloat = 0; +short a_short = 0; +float a_float = 0; struct *ptr = NULL; 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]. + and not 129FA012; or array_ptr[20] causes a SIGSEV vs. + array_ptr[0]. Status: developer-discretion if and only if the variable is assigned a value "shortly after" declaration. @@ -1359,9 +1361,9 @@ struct *ptr = NULL; Example: -ShouldWeBlockThis(); -ContainsAnImage(); -IsWebPageBlank(); +should_we_block_this(); +contains_an_image(); +is_web_page_blank(); @@ -1390,7 +1392,7 @@ IsWebPageBlank(); Example: -for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) +for ( size_t cnt = 0; cnt < block_list_length(); cnt++ ) { .... } @@ -1399,10 +1401,10 @@ for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) 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 blockListLength() call, it might even be creating and + 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 blockListLength() is a function + Remember too - even a call to block_list_length() is a function call, with the same overhead. Instead of using a function call during the iterations, @@ -1411,15 +1413,15 @@ for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) Example: -size_t len = blockListLength(); +size_t len = block_list_length(); -for ( size_t cnt = 0; cnt < len; cnt ++ ) +for ( size_t cnt = 0; cnt < len; cnt++ ) { .... } - Exceptions: if the value of blockListLength() *may* - change or could *potentially* change, then you must code the + Exceptions: 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. @@ -1625,7 +1627,7 @@ switch( hash_string( cmd ) ) 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. + load_config). Or it may really be an abort condition. Status: Programmer discretion is advised. @@ -1684,8 +1686,7 @@ switch( hash_string( cmd ) ) 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. Try to avoid using size_t if - you can. + without casting one of the values. @@ -1717,7 +1718,7 @@ long c = 0; 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 + on one line. You should, although, provide a good comment on their functions. Status: developer-discretion. @@ -1795,7 +1796,7 @@ static void unload_re_filterfile( void *f ) { ... } "Uncertain" new code and/or changes to - existing code, use FIXME + existing code, use FIXME or XXX Explanation: @@ -1832,14 +1833,14 @@ static void unload_re_filterfile( void *f ) { ... } Example for file comments: -const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.7 2006/07/18 14:48:50 david__schmidt Exp $"; +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.14 2008/01/17 01:49:51 hal9 Exp $"; /********************************************************************* * * File : $Source$ * * Purpose : (Fill me in with a good description!) * - * Copyright : Written by and Copyright (C) 2001 the SourceForge + * Copyright : Written by and Copyright (C) 2001-2007 the SourceForge * Privoxy team. http://www.privoxy.org/ * * Based on the Internet Junkbuster originally written @@ -1861,8 +1862,9 @@ const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.7 2006/07/18 14:48:5 * The GNU General Public License should be included with * this file. If not, you can view it at * http://www.gnu.org/copyleft/gpl.html - * or write to the Free Software Foundation, Inc., 59 - * Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * or write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 , + * USA * * Revisions : * $Log$ @@ -1892,14 +1894,14 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; #ifndef _FILENAME_H #define _FILENAME_H -#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.7 2006/07/18 14:48:50 david__schmidt Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.14 2008/01/17 01:49:51 hal9 Exp $" /********************************************************************* * * File : $Source$ * * Purpose : (Fill me in with a good description!) * - * Copyright : Written by and Copyright (C) 2001 the SourceForge + * Copyright : Written by and Copyright (C) 2001-2007 the SourceForge * Privoxy team. http://www.privoxy.org/ * * Based on the Internet Junkbuster originally written @@ -1921,8 +1923,9 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; * The GNU General Public License should be included with * this file. If not, you can view it at * http://www.gnu.org/copyleft/gpl.html - * or write to the Free Software Foundation, Inc., 59 - * Temple Place - Suite 330, Boston, MA 02111-1307, USA. + * or write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 , + * USA * * Revisions : * $Log$ @@ -2272,8 +2275,8 @@ at sourceforge. Three simple steps: mkdir dist # delete or choose different name if it already exists cd dist - cvs -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa login - cvs -z3 -d:pserver:anonymous@cvs.ijbswa.sourceforge.net:/cvsroot/ijbswa export -r v_X_Y_Z current + 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 @@ -2284,6 +2287,17 @@ at sourceforge. Three simple steps: on exactly the same code. + + + 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! + + + Please find additional instructions for the source tarball and the individual platform dependent binary packages below. And details @@ -2368,15 +2382,22 @@ at sourceforge. Three simple steps: - user.action is designed for local preferences. - Make sure this does not get overwritten! + user.action and user.filter + are designed for local preferences. Make sure these do not get overwritten! + config should not be overwritten either. This + has especially important configuration data in it. + trust should be left in tact as well. - Other configuration files should be installed as the new defaults, - but all previously installed configuration files should be preserved - as backups. This is just good manners :-) + Other configuration files (default.action, + default.filter and + standard.action) 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. @@ -2879,7 +2900,8 @@ at sourceforge. Three simple steps: download location, 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). + page and docs linked from the Home page (see below). Other news sites + and release oriented sites, such as Freshmeat, should also be notified. @@ -3004,6 +3026,36 @@ at sourceforge. Three simple steps: Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: developer-manual.sgml,v $ + Revision 2.14 2008/01/17 01:49:51 hal9 + Change copyright notice for docs s/2007/2008/. All these will be rebuilt soon + enough. + + Revision 2.13 2007/10/30 17:59:31 fabiankeil + - Bump p-version, p-status and copyright date. + - Mention that the manual is out of date. + - Don't use examples with HardToReadCamelCase after + explaining that we actually don't like that. + - Minor cosmetics. + + Revision 2.12 2006/11/14 01:57:46 hal9 + Dump all docs prior to 3.0.6 release. Various minor changes to faq and user + manual. + + Revision 2.11 2006/09/26 02:36:29 hal9 + Fix broken link per bug tracker. + + Revision 2.10 2006/09/22 01:27:55 hal9 + Final commit of probably various minor changes here and there. Unless + something changes this should be ready for pending release. + + Revision 2.9 2006/09/14 02:30:07 hal9 + Fix ijbswa cvs links. Update notes on release process, and which config files + should be overwritten and which not. + + Revision 2.8 2006/08/22 23:35:01 hal9 + Fix email address, cvs URI, address branching changes and various other + small updates. + Revision 2.7 2006/07/18 14:48:50 david__schmidt Reorganizing the repository: swapping out what was HEAD (the old 3.1 branch) with what was really the latest development (the v_3_0_branch branch)