From 82ca06f718357047cf1b171ac663d080cb2b1271 Mon Sep 17 00:00:00 2001 From: hal9 Date: Fri, 12 Apr 2002 03:49:53 +0000 Subject: [PATCH] Spell checked. Clarification on where docs are kept. --- doc/source/developer-manual.sgml | 134 +++++++++++++++++++------------ 1 file changed, 81 insertions(+), 53 deletions(-) diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index 1523d979..a35db57d 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -7,7 +7,7 @@ - + @@ -21,7 +21,7 @@ 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/ @@ -44,7 +44,7 @@ Privoxy Developer Manual - $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 $ @@ -79,7 +79,8 @@ You can find the latest version of the this manual at http://www.privoxy.org/developer-manual/. - Please see the Contact section on how to contact the developers. + Please see the Contact section + on how to contact the developers. @@ -159,7 +160,7 @@ Documentation Guidelines - All formal documents are maintained in docbook SGML and located in the + All formal documents are maintained in Docbook SGML and located in the doc/source/* directory. You will need Docbook, the Docbook DTD's and the Docbook modular stylesheets (or comparable alternatives), @@ -181,7 +182,7 @@ Other, less formal documents (e.g. LICENSE, INSTALL) 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. Packagers are encouraged to include this documentation. For those without @@ -200,7 +201,7 @@ Documentation writers should please make sure documents build - successfully before committing to CVS. + successfully before committing to CVS, if possible. How do you update the webserver (i.e. the pages on privoxy.org)? @@ -219,6 +220,16 @@ + + Finished docs should be occasionally submitted to CVS + (doc/webserver/*/*.html) 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 after the $VERSION and + other release specific data in configure.in has been + updated (this is done just prior to a new release). + + @@ -280,11 +291,11 @@ <command></command>, command examples. - <literallayout></literllayout>, like + <literallayout></literallayout>, like <pre>, more or less. - <itemizedlist></itemizdelist>, list with bullets. + <itemizedlist></itemizedlist>, list with bullets. <listitem></listitem>, member of the above. @@ -378,13 +389,14 @@ 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. 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. @@ -452,7 +464,7 @@ - Re-cyclable boilerplate text entities are defined like: + Re- boilerplate text entities are defined like: <!entity supported SYSTEM "supported.sgml"> @@ -473,15 +485,15 @@ p-version: the Privoxy - version string, e.g. 2.9.13. + version string, e.g. &p-version;. p-status: the project status, either - ALPHA, BETA, or STABLE. + alpha, beta, or stable. p-not-stable: use to conditionally include - text in not stable releases (e.g. BETA). + text in not stable releases (e.g. beta). p-stable: just the opposite. @@ -601,7 +613,7 @@ if ( thisVariable == thatVariable ) /* this may not either */ Exception: 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. @@ -747,7 +759,7 @@ if ( 1 == X ) Explanation: - 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. @@ -774,7 +786,7 @@ int msiis5hack = 0; int msIis5Hack = 0; Explanation: - 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. @@ -916,11 +928,11 @@ if ( this == that ) Note: 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. - Status: developer-discrection. + Status: developer-discretion. Example exception: @@ -982,7 +994,7 @@ structure->flag = ( condition ); if ( condition ) { structure->flag = 1; } else { structure->flag = 0; } - Note: The former is readable and consice. The later + Note: 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-) @@ -1063,14 +1075,14 @@ int function2( ... ) function2( ... ) { } Note: 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! - Status: developer-discrection on the number of blank + Status: developer-discretion on the number of blank lines. Enforced is the end of function comments. @@ -1138,7 +1150,7 @@ struct *ptr = NULL; and not 129FA012; or arrayPtr[20] causes a SIGSEV vs. arrayPtr[0]. - Status: developer-discrection if and only if the + Status: developer-discretion if and only if the variable is assigned a value "shortly after" declaration. @@ -1291,7 +1303,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) Note: Please! do not add "-I." to the Makefile without a _very_ good reason. This duplicates the #include - "file.h" behaviour. + "file.h" behavior. @@ -1364,9 +1376,9 @@ extern file_list *xyz; Note: 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. + file is unnecessary. - Status: Use with discrection. + Status: Use with discretion. @@ -1412,7 +1424,7 @@ switch( hash_string( cmd ) ) default : log_error( ... ); - ... anomly code goes here ... + ... anomaly code goes here ... continue; / break; / exit( 1 ); / etc ... } /* end switch( hash_string( cmd ) ) */ @@ -1423,7 +1435,7 @@ switch( hash_string( cmd ) ) This API call *should* be included in a default statement. Another Note: 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. @@ -1520,7 +1532,7 @@ long c = 0; on 1 line. You should, although, provide a good comment on their functions. - Status: developer-discrection. + Status: developer-discretion. @@ -1530,7 +1542,7 @@ long c = 0; Explanation: - 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. Only "malloc" a struct (on the heap) if the variable's life @@ -1539,7 +1551,7 @@ long c = 0; Example: 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'. @@ -1555,7 +1567,7 @@ list, then it should definately be allocated via `malloc'. 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. + free/unload/destuctor type function to accommodate this. Example: @@ -1568,7 +1580,7 @@ static void unload_re_filterfile( void *f ) { ... } functions for C run-time library functions ... such as `strdup'. - Status: developer-discrection. The "main" use of this + Status: developer-discretion. The "main" use of this standard is for allocating and freeing data structures (complex or nested). @@ -1595,16 +1607,16 @@ static void unload_re_filterfile( void *f ) { ... } "Uncertain" new code and/or changes to - exitinst code, use FIXME + existing code, use FIXME Explanation: 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: /* 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 or: @@ -1619,7 +1631,7 @@ static void unload_re_filterfile( void *f ) { ... } Note: 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). @@ -1632,7 +1644,7 @@ static void unload_re_filterfile( void *f ) { ... } Example for file comments: -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 : $Source$ @@ -1684,7 +1696,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; Note: 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. @@ -1692,7 +1704,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; #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 : $Source$ @@ -1853,7 +1865,7 @@ at sourceforge. Three simple steps: Releasing a new version - 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. @@ -1885,7 +1897,7 @@ at sourceforge. Three simple steps: Increment the version number in configure.in in - CVS. Also, inrease or reset the RPM release number in + CVS. Also, increase or reset the RPM release number in configure.in as appropriate. Do NOT touch version information after export from CVS. All packages will use the version and release data @@ -1896,8 +1908,8 @@ at sourceforge. Three simple steps: - If the default actionsfile has changed since last release, - bump up its version info in this line: + If the default actionsfile has changed since last + release, bump up its version info in this line: @@ -1924,8 +1936,8 @@ at sourceforge. Three simple steps: The first package uploaded should be the official - tarball release. This is built with the - make tarball-dist Makefile + tarball release, as required by the GPL. This is built + with the make tarball-dist Makefile target, and then can be uploaded with make tarball-upload (see below). @@ -1937,8 +1949,8 @@ at sourceforge. Three simple steps: Update the webserver 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 doc/webserver directory (or + will be able to change them)! To update the webserver, create any + pages locally in the doc/webserver/* directory (or create new directories under doc/webserver), then do @@ -1947,14 +1959,27 @@ at sourceforge. Three simple steps: + This will do the upload to the webserver (www.privoxy.org). + + Note that make dok (or make redhat-dok) creates doc/webserver/user-manual, doc/webserver/developer-manual, doc/webserver/faq and - doc/webserver/man-page automatically. + doc/webserver/index.html automatically. + (doc/webserver/man-page/privoxy-man-page.html + is created by a separate Makefile target, make + man, due to dependencies on some obscure perl scripts. + See comments in GNUmakefile.) - + + 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. + + + Please do NOT use any other means of transferring files to the webserver. make webserver not only uploads, but will make sure that the appropriate permissions are @@ -1994,7 +2019,7 @@ at sourceforge. Three simple steps: - make suse-upload or make redhat-upload + make suse-upload (or make redhat-upload) @@ -2436,6 +2461,9 @@ zip -r privoxyosx_setup_x.y.z.zip Privoxy.pkg 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 -- 2.39.2