<!entity seealso SYSTEM "seealso.sgml">
<!entity contacting SYSTEM "contacting.sgml">
<!entity copyright SYSTEM "copyright.sgml">
-<!entity p-version "2.9.13">
+<!entity p-version "2.9.14">
<!entity p-status "beta">
<!entity % p-not-stable "INCLUDE">
<!entity % p-stable "IGNORE">
This file belongs into
ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
- $Id: developer-manual.sgml,v 1.31 2002/04/11 09:32:52 oes Exp $
+ $Id: developer-manual.sgml,v 1.32 2002/04/11 21:29:58 jongfoster Exp $
Written by and Copyright (C) 2001 the SourceForge
Privoxy team. http://www.privoxy.org/
<artheader>
<title>Privoxy Developer Manual</title>
- <pubdate>$Id: developer-manual.sgml,v 1.31 2002/04/11 09:32:52 oes Exp $</pubdate>
+ <pubdate>$Id: developer-manual.sgml,v 1.32 2002/04/11 21:29:58 jongfoster Exp $</pubdate>
<authorgroup>
<author>
<para>
You can find the latest version of the this manual at <ulink
url="http://www.privoxy.org/developer-manual/">http://www.privoxy.org/developer-manual/</ulink>.
- Please see the Contact section on how to contact the developers.
+ Please see <ulink url="contact.html">the Contact section</ulink>
+ on how to contact the developers.
</para>
<!-- <para> -->
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="documentation"><title>Documentation Guidelines</title>
<para>
- All formal documents are maintained in docbook SGML and located in the
+ All formal documents are maintained in Docbook SGML and located in the
<computeroutput>doc/source/*</computeroutput> directory. You will need
<ulink url="http://www.docbook.org">Docbook</ulink>, the Docbook
DTD's and the Docbook modular stylesheets (or comparable alternatives),
<para>
Other, less formal documents (e.g. <filename>LICENSE</filename>,
<filename>INSTALL</filename>) are maintained as plain text files in the
- toplevel source directory. At least for the time being.
+ top-level source directory. At least for the time being.
</para>
<para>
Packagers are encouraged to include this documentation. For those without
</para>
<para>
Documentation writers should please make sure documents build
- successfully before committing to CVS.
+ successfully before committing to CVS, if possible.
</para>
<para>
How do you update the webserver (i.e. the pages on privoxy.org)?
</orderedlist>
</para>
+ <para>
+ Finished docs should be occasionally submitted to CVS
+ (<filename>doc/webserver/*/*.html</filename>) so that those without
+ the ability to build them locally, have access to them if needed.
+ This is especially important just prior to a new release! Please
+ do this <emphasis>after</emphasis> the <literal>$VERSION</literal> and
+ other release specific data in <filename>configure.in</filename> has been
+ updated (this is done just prior to a new release).
+ </para>
+
<!-- ~~~~~ New section ~~~~~ -->
<sect2 id="sgml">
<emphasis><command></command></emphasis>, command examples.
</member>
<member>
- <emphasis><literallayout></literllayout></emphasis>, like
+ <emphasis><literallayout></literallayout></emphasis>, like
<literal><pre></literal>, more or less.
</member>
<member>
- <emphasis><itemizedlist></itemizdelist></emphasis>, list with bullets.
+ <emphasis><itemizedlist></itemizedlist></emphasis>, list with bullets.
</member>
<member>
<emphasis><listitem></listitem></emphasis>, member of the above.
<listitem>
<para>
We have an international audience. Refrain from slang, or English
- idiosyncrasies (too many to list :).
+ idiosyncrasies (too many to list :). Humor also does not translate
+ well sometimes.
</para>
</listitem>
<listitem>
<para>
Try to keep overall line lengths in source files to 80 characters or less
- for obvious reasons. This is not always possible, with lenghty URLs for
+ for obvious reasons. This is not always possible, with lengthy URLs for
instance.
</para>
</listitem>
<itemizedlist>
<listitem>
<para>
- Re-cyclable <quote>boilerplate</quote> text entities are defined like:
+ Re- <quote>boilerplate</quote> text entities are defined like:
</para>
<para>
<literal><!entity supported SYSTEM "supported.sgml"></literal>
<simplelist>
<member>
<emphasis>p-version</emphasis>: the <application>Privoxy</application>
- version string, e.g. <quote>2.9.13</quote>.
+ version string, e.g. <quote>&p-version;</quote>.
</member>
<member>
<emphasis>p-status</emphasis>: the project status, either
- <quote>ALPHA</quote>, <quote>BETA</quote>, or <quote>STABLE</quote>.
+ <quote>alpha</quote>, <quote>beta</quote>, or <quote>stable</quote>.
</member>
<member>
<emphasis>p-not-stable</emphasis>: use to conditionally include
- text in <quote>not stable</quote> releases (e.g. <quote>BETA</quote>).
+ text in <quote>not stable</quote> releases (e.g. <quote>beta</quote>).
</member>
<member>
<emphasis>p-stable</emphasis>: just the opposite.
<para><emphasis>Exception:</emphasis></para>
<para>If you are trying to add a small logic comment and do not
- wish to "disrubt" the flow of the code, feel free to use a 1
+ wish to "disrupt" the flow of the code, feel free to use a 1
line comment which is NOT on the same line as the code.</para>
<para><emphasis>Explanation:</emphasis></para>
- <para>Use all lowercase, and seperate words via an underscore
+ <para>Use all lowercase, and separate words via an underscore
('_'). Do not start an identifier with an underscore. (ANSI C
reserves these for use by the compiler and system headers.) Do
not use identifiers which are reserved in ANSI C++. (E.g.
<para><emphasis>Explanation:</emphasis></para>
- <para>Use all lowercase, and seperate words via an underscore
+ <para>Use all lowercase, and separate words via an underscore
('_'). Do not start an identifier with an underscore. (ANSI C
reserves these for use by the compiler and system headers.) Do
not use identifiers which are reserved in ANSI C++. (E.g.
<para><emphasis>Note:</emphasis> In the special case that the if-statement is
inside a loop, and it is trivial, i.e. it tests for a
- condidtion that is obvious from the purpose of the block,
+ 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.</para>
- <para><emphasis>Status:</emphasis> developer-discrection.</para>
+ <para><emphasis>Status:</emphasis> developer-discretion.</para>
<para><emphasis>Example exception:</emphasis></para>
<programlisting>
<para>if ( condition ) { structure->flag = 1; } else {
structure->flag = 0; }</para>
- <para><emphasis>Note:</emphasis> The former is readable and consice. The later
+ <para><emphasis>Note:</emphasis> 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
I do not offend by that last comment ... 8-)</para>
function2( ... ) { }</para>
<para><emphasis>Note:</emphasis> Use 1 blank line before the closing brace and 2
- lines afterwards. This makes the end of function standout to
+ lines afterward. This makes the end of function standout to
the most casual viewer. Although function comments help
- seperate functions, this is still a good coding practice. In
+ separate functions, this is still a good coding practice. In
fact, I follow these rules when using blocks in "for", "while",
"do" loops, and long if {} statements too. After all whitespace
is free!</para>
- <para><emphasis>Status:</emphasis> developer-discrection on the number of blank
+ <para><emphasis>Status:</emphasis> developer-discretion on the number of blank
lines. Enforced is the end of function comments.</para>
and not 129FA012; or arrayPtr[20] causes a SIGSEV vs.
arrayPtr[0].</para>
- <para><emphasis>Status:</emphasis> developer-discrection if and only if the
+ <para><emphasis>Status:</emphasis> developer-discretion if and only if the
variable is assigned a value "shortly after" declaration.</para>
</sect3>
<para><emphasis>Note:</emphasis> Please! do not add "-I." to the Makefile
without a _very_ good reason. This duplicates the #include
- "file.h" behaviour.</para>
+ "file.h" behavior.</para>
</sect3>
<para><emphasis>Note:</emphasis> 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 unneccessary.</para>
+ file is unnecessary.</para>
- <para><emphasis>Status:</emphasis> Use with discrection.</para>
+ <para><emphasis>Status:</emphasis> Use with discretion.</para>
</sect3>
default :
log_error( ... );
- ... anomly code goes here ...
+ ... anomaly code goes here ...
continue; / break; / exit( 1 ); / etc ...
} /* end switch( hash_string( cmd ) ) */</programlisting>
This API call *should* be included in a default statement.</para>
<para><emphasis>Another Note:</emphasis> This is not so much a readability issue
- as a robust programming issue. The "anomly code goes here" may
+ 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>
on 1 line. You should, although, provide a good comment on
their functions.</para>
- <para><emphasis>Status:</emphasis> developer-discrection.</para>
+ <para><emphasis>Status:</emphasis> developer-discretion.</para>
</sect3>
<para><emphasis>Explanation:</emphasis></para>
- <para>Create a local stuct (on the stack) if the variable will
+ <para>Create a local struct (on the stack) if the variable will
live and die within the context of one function call.</para>
<para>Only "malloc" a struct (on the heap) if the variable's life
<para><emphasis>Example:</emphasis></para>
<programlisting>
If a function creates a struct and stores a pointer to it in a
-list, then it should definately be allocated via `malloc'.
+list, then it should definitely be allocated via `malloc'.
</programlisting>
</sect3>
responsible for ensuring that deletion is timely (i.e. not too
soon, not too late). This is known as "low-coupling" and is a
"good thing (tm)". You may need to offer a
- free/unload/destuctor type function to accomodate this.</para>
+ free/unload/destuctor type function to accommodate this.</para>
<para><emphasis>Example:</emphasis></para>
<programlisting>
functions for C run-time library functions ... such as
`strdup'.</para>
- <para><emphasis>Status:</emphasis> developer-discrection. The "main" use of this
+ <para><emphasis>Status:</emphasis> developer-discretion. The "main" use of this
standard is for allocating and freeing data structures (complex
or nested).</para>
<sect3 id="s45"><title>"Uncertain" new code and/or changes to
- exitinst code, use FIXME</title>
+ existing code, use FIXME</title>
<para><emphasis>Explanation:</emphasis></para>
<para>If you have enough confidence in new code or confidence in
- your changes, but are not *quite* sure of the reprocussions,
+ your changes, but are not *quite* sure of the repercussions,
add this:</para>
<para>/* FIXME: this code has a logic error on platform XYZ, *
- attempthing to fix */ #ifdef PLATFORM ...changed code here...
+ attempting to fix */ #ifdef PLATFORM ...changed code here...
#endif</para>
<para>or:</para>
<para><emphasis>Note:</emphasis> 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 conversly exclude from the
+ include in the project (or conversely exclude from the
project).</para>
<para><emphasis>Example for file comments:</emphasis></para>
<programlisting>
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.31 2002/04/11 09:32:52 oes Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.32 2002/04/11 21:29:58 jongfoster Exp $";
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
<para><emphasis>Note:</emphasis> The formfeed character that is present right
after the comment flower box is handy for (X|GNU)Emacs users to
- skip the verbige and get to the heart of the code (via
+ skip the verbiage and get to the heart of the code (via
`forward-page' and `backward-page'). Please include it if you
can.</para>
<programlisting>
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.31 2002/04/11 09:32:52 oes Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.32 2002/04/11 21:29:58 jongfoster Exp $"
/*********************************************************************
*
* File : $S<!-- Break CVS Substitution -->ource$
<!-- ~~~~~ New section ~~~~~ -->
<sect1 id="newrelease"><title>Releasing a new version</title>
<para>
- To minimize trouble with distribution contents, webpage
+ To minimize trouble with distribution contents, web-page
errors and the like, we strongly encourage you
to follow this section if you prepare a new release of
code or new pages on the webserver.
<listitem>
<para>
Increment the version number in <filename>configure.in</filename> in
- CVS. Also, inrease or reset the RPM release number in
+ CVS. Also, increase or reset the RPM release number in
<filename>configure.in</filename> as appropriate. Do <emphasis>NOT</emphasis>
touch version information after export from CVS.
<emphasis>All packages</emphasis> will use the version and release data
</listitem>
<listitem>
<para>
- If the default actionsfile has changed since last release,
- bump up its version info in this line:
+ If the default <filename>actionsfile</filename> has changed since last
+ release, bump up its version info in this line:
</para>
<para>
<programlisting>
<listitem>
<para>
The first package uploaded should be the official
- <quote>tarball</quote> release. This is built with the
- <quote><command>make tarball-dist</command></quote> Makefile
+ <quote>tarball</quote> release, as required by the GPL. This is built
+ with the <quote><command>make tarball-dist</command></quote> Makefile
target, and then can be uploaded with
<quote><command>make tarball-upload</command></quote> (see below).
</para>
<sect2 id="newrelease-web"><title>Update the webserver</title>
<para>
All files must be group-readable and group-writable (or no one else
- will be able to change them). To update the webserver, create any
- pages locally in the <filename>doc/webserver</filename> directory (or
+ will be able to change them)! To update the webserver, create any
+ pages locally in the <filename>doc/webserver/*</filename> directory (or
create new directories under <filename>doc/webserver</filename>), then do
</para>
<para>
</programlisting>
</para>
<para>
+ This will do the upload to the webserver (www.privoxy.org).
+ </para>
+ <para>
Note that <quote><command>make dok</command></quote>
(or <quote><command>make redhat-dok</command></quote>) creates
<filename>doc/webserver/user-manual</filename>,
<filename>doc/webserver/developer-manual</filename>,
<filename>doc/webserver/faq</filename> and
- <filename>doc/webserver/man-page</filename> automatically.
+ <filename>doc/webserver/index.html</filename> automatically.
+ (<filename>doc/webserver/man-page/privoxy-man-page.html</filename>
+ is created by a separate Makefile target, <quote><command>make
+ man</command></quote>, due to dependencies on some obscure perl scripts.
+ See comments in <filename>GNUmakefile</filename>.)
</para>
- <para>
+ <para>
+ Someone should also commit these to CVS so that packagers without the
+ ability to build docs locally, have access to them. This is a separate
+ step, and should also be done before each official release.
+ </para>
+
+ <para>
Please do NOT use any other means of transferring files to the
webserver. <quote><command>make webserver</command></quote> not only
uploads, but will make sure that the appropriate permissions are
</para>
<para>
<programlisting>
- make suse-upload or make redhat-upload
+ make suse-upload (or make redhat-upload)
</programlisting>
</para>
<para>
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: developer-manual.sgml,v $
+ Revision 1.32 2002/04/11 21:29:58 jongfoster
+ Documenting Win32 release procedure
+
Revision 1.31 2002/04/11 09:32:52 oes
more nits
projects / privoxy.git / commitdiff