X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=d956b844f31d85e4dbfdaba6a37e643067e09350;hp=362b5f5bbbc26e6173bc67aba9a7fdc9410905e7;hb=89a290c32e6be1cb5c24f8bef09240c1fd0d181f;hpb=be490aaf495531c679f5eec40c2f548ff3d56d2c diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index 362b5f5b..d956b844 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -8,8 +8,8 @@ - - + + @@ -23,9 +23,9 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: developer-manual.sgml,v 2.10 2006/09/22 01:27:55 hal9 Exp $ + $Id: developer-manual.sgml,v 2.24 2009/01/13 16:50:35 fabiankeil Exp $ - Copyright (C) 2001-2006 Privoxy Developers http://privoxy.org + Copyright (C) 2001-2008 Privoxy Developers http://www.privoxy.org/ See LICENSE. ======================================================================== @@ -44,13 +44,13 @@ - Copyright &my-copy; 2001-2006 by - Privoxy Developers + Copyright &my-copy; 2001-2008 by + Privoxy Developers - $Id: developer-manual.sgml,v 2.10 2006/09/22 01:27:55 hal9 Exp $ + $Id: developer-manual.sgml,v 2.24 2009/01/13 16:50:35 fabiankeil Exp $ @@ -119,29 +120,21 @@ 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 GNU General Public License version 2. + 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. Quickstart to Privoxy Development - The first step is to join the developer's mailing list. @@ -731,8 +724,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 +739,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 +773,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 +820,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 +839,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 +916,7 @@ short DoSomethingVeryImportant( if ( 1 == X ) { - DoSomethingVeryImportant(); + do_something_very_important(); ...some long list of commands... } /* -END- if x is 1 */ @@ -931,7 +924,7 @@ or: if ( 1 == X ) { - DoSomethingVeryImportant(); + do_something_very_important(); ...some long list of commands... } /* -END- if ( 1 == X ) */ @@ -1148,17 +1141,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 +1194,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 +1221,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 +1240,7 @@ FunctionName(); int function1( ... ) { ...code... - return( retCode ); + return( ret_code ); } /* -END- function1 */ @@ -1259,7 +1252,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 +1322,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 +1352,9 @@ struct *ptr = NULL; Example: -ShouldWeBlockThis(); -ContainsAnImage(); -IsWebPageBlank(); +should_we_block_this(); +contains_an_image(); +is_web_page_blank(); @@ -1390,7 +1383,7 @@ IsWebPageBlank(); Example: -for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) +for ( size_t cnt = 0; cnt < block_list_length(); cnt++ ) { .... } @@ -1399,10 +1392,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 +1404,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 +1618,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 +1677,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 +1709,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 +1787,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,19 +1824,15 @@ static void unload_re_filterfile( void *f ) { ... } Example for file comments: -const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.10 2006/09/22 01:27:55 hal9 Exp $"; +const char FILENAME_rcs[] = "$Id$"; /********************************************************************* * * File : $Source$ * * Purpose : (Fill me in with a good description!) * - * Copyright : Written by and Copyright (C) 2001-2006 the SourceForge - * Privoxy team. http://www.privoxy.org/ - * - * Based on the Internet Junkbuster originally written - * by and Copyright (C) 1997 Anonymous Coders and - * Junkbusters Corporation. http://www.junkbusters.com + * Copyright : Written by and Copyright (C) 2001-2009 + * the Privoxy team. http://www.privoxy.org/ * * This program is free software; you can redistribute it * and/or modify it under the terms of the GNU General @@ -1860,7 +1848,7 @@ const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.10 2006/09/22 01:27: * * 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 + * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html * or write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 , * USA @@ -1893,19 +1881,15 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; #ifndef _FILENAME_H #define _FILENAME_H -#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.10 2006/09/22 01:27:55 hal9 Exp $" +#define FILENAME_H_VERSION "$Id$" /********************************************************************* * * File : $Source$ * * Purpose : (Fill me in with a good description!) * - * Copyright : Written by and Copyright (C) 2001-2006 the SourceForge - * Privoxy team. http://www.privoxy.org/ - * - * Based on the Internet Junkbuster originally written - * by and Copyright (C) 1997 Anonymous Coders and - * Junkbusters Corporation. http://www.junkbusters.com + * Copyright : Written by and Copyright (C) 2001-2009 + * the Privoxy team. http://www.privoxy.org/ * * This program is free software; you can redistribute it * and/or modify it under the terms of the GNU General @@ -1921,7 +1905,7 @@ 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 + * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html * or write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 , * USA @@ -2390,9 +2374,8 @@ at sourceforge. Three simple steps: - Other configuration files (default.action, - default.filter and - standard.action) should be installed as the new + Other configuration files (default.action and + default.filter) 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 @@ -2677,11 +2660,11 @@ at sourceforge. Three simple steps: - Mac OSX + Mac OS X First, make sure that you have freshly exported the right version into an empty directory. (See "Building and releasing - packages" above). Then get the Mac OSX setup module: + packages" above). Then get the Mac OS X setup module: @@ -2863,7 +2846,9 @@ at sourceforge. Three simple steps: Or use the make targets as described above. - Once this done go to http://sourceforge.net/project/admin/editpackages.php?group_id=11118, + Once this done go to https://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 Release. You will then need to create a new release for your package, using the format @@ -3025,6 +3010,56 @@ at sourceforge. Three simple steps: Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: developer-manual.sgml,v $ + Revision 2.24 2009/01/13 16:50:35 fabiankeil + The standard.action file is gone. + + Revision 2.23 2008/09/26 17:02:01 fabiankeil + - Break some more CVS substitutions in examples. + - Remove Junkbusters reference in example header + for new files. + + Revision 2.22 2008/08/30 15:37:35 fabiankeil + Update entities. + + Revision 2.21 2008/08/16 08:51:28 fabiankeil + Update version-related entities. + + Revision 2.20 2008/06/14 13:21:24 fabiankeil + Prepare for the upcoming 3.0.9 beta release. + + Revision 2.19 2008/05/12 11:13:33 fabiankeil + Clarify that Privoxy is licensed under GPL version 2. + + Revision 2.18 2008/02/04 12:14:06 fabiankeil + Change "Edit Packages" URL to use https. + + Revision 2.17 2008/02/03 21:37:41 hal9 + Apply patch from Mark: s/OSX/OS X/ + + Revision 2.16 2008/01/19 17:52:38 hal9 + Re-commit to fix various minor issues for new release. + + Revision 2.15 2008/01/19 15:03:05 hal9 + Doc sources tagged for 3.0.8 release. + + 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. @@ -3177,7 +3212,7 @@ at sourceforge. Three simple steps: More boilerplate text for use across multiple docs. Revision 1.20 2002/04/04 03:28:27 david__schmidt - Add Mac OSX section + Add Mac OS X section Revision 1.19 2002/04/03 15:09:42 david__schmidt Add OS/2 build section