<!entity contacting SYSTEM "contacting.sgml">
<!entity copyright SYSTEM "copyright.sgml">
<!entity license SYSTEM "license.sgml">
-<!entity p-version "3.0.6">
-<!entity p-status "stable">
-<!entity % p-not-stable "IGNORE">
-<!entity % p-stable "INCLUDE">
+<!entity p-version "3.0.14">
+<!entity p-status "BETA">
+<!entity % p-not-stable "INCLUDE">
+<!entity % p-stable "IGNORE">
<!entity % p-text "IGNORE"> <!-- define we are not a text only doc -->
<!entity % p-doc "INCLUDE"> <!-- and we are a formal doc -->
+<!entity % seealso-extra "INCLUDE"> <!-- extra stuff from seealso.sgml -->
<!entity my-copy "©"> <!-- kludge for docbook2man -->
]>
<!--
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: developer-manual.sgml,v 2.11 2006/09/26 02:36:29 hal9 Exp $
+ $Id: developer-manual.sgml,v 2.29 2009/06/12 14:30:58 fabiankeil Exp $
- Copyright (C) 2001-2006 Privoxy Developers http://privoxy.org
+ Copyright (C) 2001-2009 Privoxy Developers http://www.privoxy.org/
See LICENSE.
========================================================================
<subscript>
<!-- Completely the wrong markup, but very little is allowed -->
<!-- in this part of an article. FIXME -->
- <link linkend="copyright">Copyright</link> &my-copy; 2001-2006 by
- <ulink url="http://www.privoxy.org">Privoxy Developers</ulink>
+ <link linkend="copyright">Copyright</link> &my-copy; 2001-2009 by
+ <ulink url="http://www.privoxy.org/">Privoxy Developers</ulink>
</subscript>
</pubdate>
- <pubdate>$Id: developer-manual.sgml,v 2.11 2006/09/26 02:36:29 hal9 Exp $</pubdate>
+ <pubdate>$Id: developer-manual.sgml,v 2.29 2009/06/12 14:30:58 fabiankeil Exp $</pubdate>
<!--
The developer manual provides guidance on coding, testing, packaging, documentation
and other issues of importance to those involved with
<application>Privoxy</application> development. It is mandatory (and helpful!) reading
- for anyone who wants to join the team.
+ for anyone who wants to join the team. Note that it's currently out of date
+ and may not be entirely correct. As always, patches are welcome.
</para>
<!-- Include privoxy.sgml boilerplate text: -->
-->
<para>
<application>Privoxy</application>, as an heir to
- <application>Junkbuster</application>, is an Open Source project
- and licensed under the GPL. As such, <application>Privoxy</application>
- 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 <application>Privoxy</application>, and
+ <application>Junkbuster</application>, is a Free Software project
+ and the code is licensed under the GNU General Public License version 2.
+ As such, <application>Privoxy</application> 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 <application>Privoxy</application>, and
to make it available to as wide an audience as possible.
</para>
<para>
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.
</para>
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="quickstart"><title>Quickstart to Privoxy Development</title>
- <!--
- <para>
- You'll need an account on <ulink
- url="http://sourceforge.net/">Sourceforge</ulink> to support our
- development. Mail your ID to <ulink
- url="mailto:developers@privoxy.org">the list</ulink> and wait until a
- project manager has added you.
- </para>
- -->
<para>
The first step is to join the <ulink
url="mailto:ijbswa-developers@lists.sourceforge.net">developer's mailing list</ulink>.
<para><emphasis>Explanation:</emphasis></para>
<para>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
<para><emphasis>Example:</emphasis></para>
<programlisting>
/* 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 ...
}
/*********************************************************************
* 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();
}</programlisting>
<para><emphasis>Exception:</emphasis></para>
* 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*/
}
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 */
</programlisting>
</sect3>
<programlisting>
if ( 1 == X )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
...some long list of commands...
} /* -END- if x is 1 */
if ( 1 == X )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
...some long list of commands...
} /* -END- if ( 1 == X ) */
</programlisting>
<programlisting>
if ( this == that )
{
- DoSomething();
- DoSomethingElse();
+ do_something();
+ do_something_else();
}</programlisting>
<para><emphasis>Instead of:</emphasis></para>
- <para>if ( this == that ) DoSomething(); DoSomethingElse();</para>
+ <para>if ( this == that ) do_something(); do_something_else();</para>
<para>or</para>
- <para>if ( this == that ) DoSomething();</para>
+ <para>if ( this == that ) do_something();</para>
<para><emphasis>Note:</emphasis> The first example in "Instead of" will execute
in a manner other than that which the developer desired (per
<para><emphasis>Example:</emphasis></para>
<programlisting>
-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 )
</programlisting>
</sect3>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-aStruct->aMember;
-aStruct.aMember;
-FunctionName();</programlisting>
+a_struct->a_member;
+a_struct.a_member;
+function_name();</programlisting>
- <para><emphasis>Instead of:</emphasis> aStruct -> aMember; aStruct . aMember;
- FunctionName ();</para>
+ <para><emphasis>Instead of:</emphasis> a_struct -> a_member; a_struct . a_member;
+ function_name ();</para>
</sect3>
int function1( ... )
{
...code...
- return( retCode );
+ return( ret_code );
} /* -END- function1 */
<para><emphasis>Instead of:</emphasis></para>
- <para>int function1( ... ) { ...code... return( retCode ); } int
+ <para>int function1( ... ) { ...code... return( ret_code ); } int
function2( ... ) { }</para>
<para><emphasis>Note:</emphasis> Use 1 blank line before the closing brace and 2
<para><emphasis>Example:</emphasis></para>
<programlisting>
-short anShort = 0;
-float aFloat = 0;
+short a_short = 0;
+float a_float = 0;
struct *ptr = NULL;</programlisting>
<para><emphasis>Note:</emphasis> 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].</para>
+ and not 129FA012; or array_ptr[20] causes a SIGSEV vs.
+ array_ptr[0].</para>
<para><emphasis>Status:</emphasis> developer-discretion if and only if the
variable is assigned a value "shortly after" declaration.</para>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-ShouldWeBlockThis();
-ContainsAnImage();
-IsWebPageBlank();
+should_we_block_this();
+contains_an_image();
+is_web_page_blank();
</programlisting>
</sect3>
<para><emphasis>Example:</emphasis></para>
<programlisting>
-for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
+for ( size_t cnt = 0; cnt < block_list_length(); cnt++ )
{
....
}</programlisting>
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.</para>
<para>Instead of using a function call during the iterations,
<para><emphasis>Example:</emphasis></para>
<programlisting>
-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++ )
{
....
}</programlisting>
- <para><emphasis>Exceptions:</emphasis> if the value of blockListLength() *may*
- change or could *potentially* change, then you must code the
+ <para><emphasis>Exceptions:</emphasis> 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.</para>
<para><emphasis>Another Note:</emphasis> 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.</para>
+ load_config). Or it may really be an abort condition.</para>
<para><emphasis>Status:</emphasis> Programmer discretion is advised.</para>
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.</para>
+ without casting one of the values.</para>
</sect3>
<para><emphasis>Exceptions:</emphasis> 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.</para>
<para><emphasis>Status:</emphasis> developer-discretion.</para>
<sect3 id="s45"><title>"Uncertain" new code and/or changes to
- existing code, use FIXME</title>
+ existing code, use FIXME or XXX</title>
<para><emphasis>Explanation:</emphasis></para>
<para><emphasis>Example for file comments:</emphasis></para>
<programlisting>
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.11 2006/09/26 02:36:29 hal9 Exp $";
+const char FILENAME_rcs[] = "$I<!-- Break CVS Substitution -->d$";
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
*
* 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
*
* 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
*
- * Revisions :
- * $L<!-- Break CVS Substitution -->og$
- *
*********************************************************************/
<programlisting>
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.11 2006/09/26 02:36:29 hal9 Exp $"
+#define FILENAME_H_VERSION "$I<!-- Break CVS Substitution -->d$"
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
*
* 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
*
* 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
*
- * Revisions :
- * $L<!-- Break CVS Substitution -->og$
- *
*********************************************************************/
</listitem>
<listitem>
<para>
- Other configuration files (<filename>default.action</filename>,
- <filename>default.filter</filename> and
- <filename>standard.action</filename>) should be installed as the new
+ Other configuration files (<filename>default.action</filename> and
+ <filename>default.filter</filename>) 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
</para>
</sect3>
- <sect3 id="newrelease-macosx"><title>Mac OSX</title>
+ <sect3 id="newrelease-macosx"><title>Mac OS X</title>
<para>
First, <emphasis>make sure that you have freshly exported the right
version into an empty directory</emphasis>. (See "Building and releasing
- packages" above). Then get the Mac OSX setup module:
+ packages" above). Then get the Mac OS X setup module:
</para>
<para>
<programlisting>
Or use the <command>make</command> targets as described above.
</para>
<para>
- Once this done go to <ulink url="http://sourceforge.net/project/admin/editpackages.php?group_id=11118">http://sourceforge.net/project/admin/editpackages.php?group_id=11118</ulink>,
+ Once this done go to <ulink
+ url="https://sourceforge.net/project/admin/editpackages.php?group_id=11118"
+ >https://sourceforge.net/project/admin/editpackages.php?group_id=11118</ulink>,
making sure you are logged in. Find your target platform in the
second column, and click <literal>Add Release</literal>. You will
then need to create a new release for your package, using the format
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: developer-manual.sgml,v $
+ Revision 2.29 2009/06/12 14:30:58 fabiankeil
+ Update entities for 3.0.13 beta.
+
+ Revision 2.28 2009/05/16 13:27:21 fabiankeil
+ Remove CVS revision logs. TODO item #33.
+
+ Revision 2.27 2009/02/19 02:20:22 hal9
+ Make some links in seealso conditional. Man page is now privoxy only links.
+
+ Revision 2.26 2009/02/12 16:08:26 fabiankeil
+ Declare the code stable.
+
+ Revision 2.25 2009/02/12 15:37:05 fabiankeil
+ Update templates.
+
+ 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.
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
projects / privoxy.git / blobdiff