></P
><P
>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.</P
></DIV
><DIV
>Explanation:</I
></P
><P
->Use all lowercase, and seperate words via an underscore
+>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.
>Explanation:</I
></P
><P
->Use all lowercase, and seperate words via an underscore
+>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.
>Note:</I
> 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.</P
><P
><I
CLASS="EMPHASIS"
>Status:</I
-> developer-discrection.</P
+> developer-discretion.</P
><P
><I
CLASS="EMPHASIS"
><I
CLASS="EMPHASIS"
>Note:</I
-> The former is readable and consice. The later
+> 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-)</P
CLASS="EMPHASIS"
>Note:</I
> 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!</P
><I
CLASS="EMPHASIS"
>Status:</I
-> developer-discrection on the number of blank
+> developer-discretion on the number of blank
lines. Enforced is the end of function comments.</P
></DIV
><DIV
><I
CLASS="EMPHASIS"
>Status:</I
-> developer-discrection if and only if the
+> developer-discretion if and only if the
variable is assigned a value "shortly after" declaration.</P
></DIV
></DIV
>Note:</I
> Please! do not add "-I." to the Makefile
without a _very_ good reason. This duplicates the #include
- "file.h" behaviour.</P
+ "file.h" behavior.</P
></DIV
><DIV
CLASS="SECT3"
> 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.</P
+ file is unnecessary.</P
><P
><I
CLASS="EMPHASIS"
>Status:</I
-> Use with discrection.</P
+> Use with discretion.</P
></DIV
></DIV
><DIV
default :
log_error( ... );
- ... anomly code goes here ...
+ ... anomaly code goes here ...
continue; / break; / exit( 1 ); / etc ...
} /* end switch( hash_string( cmd ) ) */</PRE
CLASS="EMPHASIS"
>Another Note:</I
> 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.</P
><P
><I
CLASS="EMPHASIS"
>Status:</I
-> developer-discrection.</P
+> developer-discretion.</P
></DIV
><DIV
CLASS="SECT3"
>Explanation:</I
></P
><P
->Create a local stuct (on the stack) if the variable will
+>Create a local struct (on the stack) if the variable will
live and die within the context of one function call.</P
><P
>Only "malloc" a struct (on the heap) if the variable's life
><PRE
CLASS="PROGRAMLISTING"
>If a function creates a struct and stores a pointer to it in a
-list, then it should definately be allocated via `malloc'.</PRE
+list, then it should definitely be allocated via `malloc'.</PRE
></TD
></TR
></TABLE
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.</P
+ free/unload/destuctor type function to accommodate this.</P
><P
><I
CLASS="EMPHASIS"
><I
CLASS="EMPHASIS"
>Status:</I
-> developer-discrection. The "main" use of this
+> developer-discretion. The "main" use of this
standard is for allocating and freeing data structures (complex
or nested).</P
></DIV
><A
NAME="S45"
>5.7.10. "Uncertain" new code and/or changes to
- exitinst code, use FIXME</A
+ existing code, use FIXME</A
></H3
><P
><I
></P
><P
>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:</P
><P
>/* 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</P
><P
>or:</P
>Note:</I
> 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).</P
></DIV
></DIV
><TD
><PRE
CLASS="PROGRAMLISTING"
->const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.28 2002/04/08 22:59:26 hal9 Exp $";
+>const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.31 2002/04/11 09:32:52 oes Exp $";
/*********************************************************************
*
* File : $Source$
>Note:</I
> 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.</P
><P
CLASS="PROGRAMLISTING"
>#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.28 2002/04/08 22:59:26 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.31 2002/04/11 09:32:52 oes Exp $"
/*********************************************************************
*
* File : $Source$
>4. Documentation Guidelines</A
></H1
><P
-> All formal documents are maintained in docbook SGML and located in the
+> All formal documents are maintained in Docbook SGML and located in the
<TT
CLASS="COMPUTEROUTPUT"
>doc/source/*</TT
CLASS="FILENAME"
>INSTALL</TT
>) 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.
</P
><P
> Packagers are encouraged to include this documentation. For those without
></OL
>
</P
+><P
+> Finished docs should be occasionally submitted to CVS
+ (<TT
+CLASS="FILENAME"
+>doc/webserver/*/*.html</TT
+>) 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 <I
+CLASS="EMPHASIS"
+>after</I
+> the <TT
+CLASS="LITERAL"
+>$VERSION</TT
+> and
+ other release specific data in <TT
+CLASS="FILENAME"
+>configure.in</TT
+> has been
+ updated (this is done just prior to a new release).
+ </P
><DIV
CLASS="SECT2"
><H2
><TD
> <I
CLASS="EMPHASIS"
-><literallayout></literllayout></I
+><literallayout></literallayout></I
>, like
<TT
CLASS="LITERAL"
><TD
> <I
CLASS="EMPHASIS"
-><itemizedlist></itemizdelist></I
+><itemizedlist></itemizedlist></I
>, list with bullets.
</TD
></TR
><LI
><P
> 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.
</P
></LI
><LI
><P
> 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.
</P
></LI
><H2
CLASS="SECT2"
><A
-NAME="AEN179"
+NAME="AEN185"
>4.3. Privoxy Custom Entities</A
></H2
><P
><UL
><LI
><P
-> Re-cyclable <SPAN
+> Re- <SPAN
CLASS="QUOTE"
>"boilerplate"</SPAN
> text entities are defined like:
>
version string, e.g. <SPAN
CLASS="QUOTE"
->"2.9.13"</SPAN
+>"2.9.14"</SPAN
>.
</TD
></TR
>: the project status, either
<SPAN
CLASS="QUOTE"
->"ALPHA"</SPAN
+>"alpha"</SPAN
>, <SPAN
CLASS="QUOTE"
->"BETA"</SPAN
+>"beta"</SPAN
>, or <SPAN
CLASS="QUOTE"
->"STABLE"</SPAN
+>"stable"</SPAN
>.
</TD
></TR
>"not stable"</SPAN
> releases (e.g. <SPAN
CLASS="QUOTE"
->"BETA"</SPAN
+>"beta"</SPAN
>).
</TD
></TR
>Releasing a new version</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.60"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.64
+"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
>8. Releasing a new version</A
></H1
><P
-> 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.
CLASS="FILENAME"
>configure.in</TT
> in
- CVS. Also, inrease or reset the RPM release number in
+ CVS. Also, increase or reset the RPM release number in
<TT
CLASS="FILENAME"
>configure.in</TT
></LI
><LI
><P
-> If the default actionsfile has changed since last release,
- bump up its version info in this line:
+> If the default <TT
+CLASS="FILENAME"
+>actionsfile</TT
+> has changed since last
+ release, bump up its version info in this line:
</P
><P
>
<SPAN
CLASS="QUOTE"
>"tarball"</SPAN
-> release. This is built with the
- <SPAN
+> release, as required by the GPL. This is built
+ with the <SPAN
CLASS="QUOTE"
>"<B
CLASS="COMMAND"
>make tarball-dist</B
>"</SPAN
-> Makefile
+> Makefile
target, and then can be uploaded with
<SPAN
CLASS="QUOTE"
></H2
><P
> 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
+ will be able to change them)! To update the webserver, create any
pages locally in the <TT
CLASS="FILENAME"
->doc/webserver</TT
+>doc/webserver/*</TT
> directory (or
create new directories under <TT
CLASS="FILENAME"
>
</P
><P
+> This will do the upload to the webserver (www.privoxy.org).
+ </P
+><P
> Note that <SPAN
CLASS="QUOTE"
>"<B
> and
<TT
CLASS="FILENAME"
->doc/webserver/man-page</TT
+>doc/webserver/index.html</TT
> automatically.
+ (<TT
+CLASS="FILENAME"
+>doc/webserver/man-page/privoxy-man-page.html</TT
+>
+ is created by a separate Makefile target, <SPAN
+CLASS="QUOTE"
+>"<B
+CLASS="COMMAND"
+>make
+ man</B
+>"</SPAN
+>, due to dependencies on some obscure perl scripts.
+ See comments in <TT
+CLASS="FILENAME"
+>GNUmakefile</TT
+>.)
</P
><P
+>
+ 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.
+ </P
+><P
> Please do NOT use any other means of transferring files to the
webserver. <SPAN
CLASS="QUOTE"
><TD
><PRE
CLASS="PROGRAMLISTING"
-> make suse-upload or make redhat-upload
+> make suse-upload (or make redhat-upload)
</PRE
></TD
></TR
projects / privoxy.git / commitdiff