From 6c57654c56fc87fecf213110838dc0bad33a1d63 Mon Sep 17 00:00:00 2001 From: hal9 Date: Fri, 12 Apr 2002 01:56:39 +0000 Subject: [PATCH] Spell checked (ouch). A few small clarifications on docs locations. --- doc/webserver/developer-manual/coding.html | 54 +++++++++---------- doc/webserver/developer-manual/copyright.html | 6 ++- .../developer-manual/documentation.html | 48 ++++++++++++----- doc/webserver/developer-manual/index.html | 17 +++--- .../developer-manual/newrelease.html | 53 +++++++++++++----- .../developer-manual/quickstart.html | 2 +- 6 files changed, 119 insertions(+), 61 deletions(-) diff --git a/doc/webserver/developer-manual/coding.html b/doc/webserver/developer-manual/coding.html index 2e1d8792..d20b0628 100644 --- a/doc/webserver/developer-manual/coding.html +++ b/doc/webserver/developer-manual/coding.html @@ -224,7 +224,7 @@ CLASS="EMPHASIS" >

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.

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. @@ -489,7 +489,7 @@ CLASS="EMPHASIS" >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. @@ -780,14 +780,14 @@ CLASS="EMPHASIS" >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.

developer-discretion.

Note: 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-)

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 +> developer-discretion on the number of blank lines. Enforced is the end of function comments.

Status: developer-discrection if and only if the +> developer-discretion if and only if the variable is assigned a value "shortly after" declaration.

Note: Please! do not add "-I." to the Makefile without a _very_ good reason. This duplicates the #include - "file.h" behaviour.

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.

Status: Use with discrection.

Use with discretion.

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.

Status: developer-discrection.

developer-discretion.

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 @@ -1866,7 +1866,7 @@ WIDTH="100%" >

If a function creates a struct and stores a pointer to it in a
-list, then it should definately be allocated via `malloc'.

Status: 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).

5.7.10. "Uncertain" new code and/or changes to - exitinst code, use FIXME

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:

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).

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$
@@ -2079,7 +2079,7 @@ CLASS="EMPHASIS"
 >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.
#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$
diff --git a/doc/webserver/developer-manual/copyright.html b/doc/webserver/developer-manual/copyright.html
index 152577b6..3e822d82 100644
--- a/doc/webserver/developer-manual/copyright.html
+++ b/doc/webserver/developer-manual/copyright.html
@@ -78,7 +78,7 @@ CLASS="SECT2"
 >
10.1. Copyright
 is free software; you can
  redistribute it and/or modify it under the terms of the GNU General Public
  
+
  License as published by the Free Software Foundation; either version 2 of the
  License, or (at your option) any later version.
 This program is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
+ 
  more details, which is available from the Free Software Foundation, Inc, 59
  Temple Place - Suite 330, Boston, MA  02111-1307, USA.
10.2. History
4. 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/*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
@@ -224,6 +224,27 @@ CLASS="COMPUTEROUTPUT"
 >
   
   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).
+  
  <literallayout></literllayout><literallayout></literallayout>, like 
     <itemizedlist></itemizdelist><itemizedlist></itemizedlist>, list with bullets.
  
  •      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.
    
    • 4.3. Privoxy Custom Entities
    •     Re-cyclable     Re- "boilerplate" text entities are defined like:
@@ -678,7 +700,7 @@ CLASS="APPLICATION"
 > 
     version string, e.g. "2.9.13""2.9.14".
    : the project status, either 
     "ALPHA""alpha", "BETA""beta", or "STABLE""stable".
    "not stable" releases (e.g. "BETA""beta").
    
    $Id: developer-manual.sgml,v 1.28 2002/04/08 22:59:26 hal9 Exp $
    $Id: developer-manual.sgml,v 1.31 2002/04/11 09:32:52 oes Exp $
    http://www.privoxy.org/developer-manual/.
- Please see the Contact section on how to contact the developers.
    the Contact section 
+ on how to contact the developers.
    4.3. Privoxy Custom Entities
    5.7.10. "Uncertain" new code and/or changes to
-    exitinst code, use FIXME
    10.1. Copyright
    10.2. History
    Releasing a new version8. 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.
@@ -130,7 +131,7 @@ CLASS="QUOTE"
 CLASS="FILENAME"
 >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
  •         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:
        
     
@@ -206,14 +210,14 @@ CLASS="COMMAND"
         "tarball" release. This is built with the
-         release, as required by the GPL. This is built
+        with the "make tarball-dist" Makefile 
+> Makefile
         target, and then can be uploaded with 
         
    	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 doc/webserverdoc/webserver/* directory (or
 	create new directories under 
 	
          This will do the upload to the webserver (www.privoxy.org).      
+     
    	Note that " and
 	doc/webserver/man-pagedoc/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 suse-upload or make redhat-upload
+>  make suse-upload (or make redhat-upload)
 	
  • 	      	A bugfix / clean-up / cosmetic thing: shoot
+>	      	A bug-fix / clean-up / cosmetic thing: shoot