update

git-svn-id: http://svn.code.sf.net/p/netpbm/code/trunk@1206 9d0c8265-081b-0410-96cb-a4ca84ce46f8

1 files changed, 41 insertions, 63 deletions

diff --git a/doc/Netpbm.programming b/doc/Netpbm.programming
index 14de8b08..bd1c3596 100644
--- a/doc/Netpbm.programming
+++ b/doc/Netpbm.programming
@@ -48,17 +48,18 @@ DEVELOPMENT PROCESS
 -------------------
 
 Just email your code to the Netpbm maintainer.  Base it on the most recent
-Latest Netpbm release if possible.  It's a good idea to ask the maintainer
-before starting a big change to a file to make sure it doesn't conflict
-with some other work that has been done since the last release.
+Netpbm Development release if possible.
 
 The preferred form for changes to existing files is a unified diff patch --
-the conventional Unix means of communicating code changes.
+the conventional Unix means of communicating code changes.  A Subversion
+'svn diff' creates that easily.
 
-You should update or create documentation too.  The source files for
-the documentation are the HTML files at
-http://netpbm.sourceforge.net.doc/ .  But if you don't, the Netpbm
-maintainer will do the update before releasing your code.
+You should update or create documentation too.  But if you don't, the Netpbm
+maintainer will do the update before releasing your code.  The source files
+for the documentation are the HTML files in the 'userguide' directory of the
+Netpbm Subversion repository:
+http://netpbm.svn.sourceforge.net/svnroot/netpbm/userguide .  The identical
+files are at http://netpbm.sourceforge.net/doc/ .
 
 There are some automated tests in the package - shell scripts in files
 named such as "pbmtog3.test".  You can use those to verify your
@@ -88,40 +89,14 @@ before you read these.
   but don't depend very much on these; use the library functions
   instead to read and write the image files.
 
-* Your new program must belong to one of the four Netpbm classes,
-  which are loosely based on the Netpbm formats.  They are defined as
-  follows:
-
-  pbm: These programs take PBM (bitmap - pixels are black or white)
-       files as input or output or both.  They never have PGM or PPM 
-       primary input or output.  They use the libpbm Netpbm
-       library.  They have "pbm" in their names.
-
-  pgm: These programs take PBM or PGM (grayscale) files as input, or
-       produce PGM files as output, or both.  They treat PBM input
-       as if it were the equivalent PGM input.  They never produce PBM
-       primary output and never have PPM primary input or output.
-       They use the libpbm and libpgm Netpbm libraries.  They have
-       "pgm" in their names.
-
-  ppm: These programs take PBM or PGM or PPM (color) files as input,
-       or produce PPM files as output, or both.  They treat PBM and
-       PGM input as if it were the equivalent PPM input.  They never
-       produce PBM or PGM primary output.  They use the libpbm,
-       libpgm, and libppm Netpbm libraries.  They have "ppm" in their
-       names.
-
-  pnm: These are the most general programs.  They handle all four
-       Netpbm formats (PBM, PGM, PPM, and PAM).  They use all Netpbm
-       formats as input or output or both.  They recognize the
-       difference between PBM, PGM, and PPM input, so a PBM input
-       might produce a different result than the equivalent PGM input.
-       These programs use the libpbm, libpgm, libppm, and libpnm
-       Netpbm libraries.  They have "pnm" or "pam" in their names.
-
-  Decide which one of these classes your program belongs to.  Your choice
-  determines the proper naming of the program and which set of library
-  subroutines you should use.
+* You should try to use the "pam" library functions, which are newer than the
+  "pbm", "pgm", and "pnm" ones.  The "pam" functions read and write all four
+  Netpbm formats and make code easier to write and to read.
+
+* A new program should generate PAM output.  Note that any program that uses
+  the modern Netpbm library can read PAM even if it was designed for the older
+  formats.  For other programs, one can convert PAM to the older formats
+  with 'pamtopnm'.
 
 * If your program involves transparency (alpha masks), you have two
   alternatives.  The older method is to use a separate PGM file for the
@@ -137,9 +112,6 @@ before you read these.
   cause problems to other programs when you do a "merge build" of 
   Netpbm.
 
-* Declare main() with return type 'int', not 'void'.  Some systems won't
-  compile void main().
-
 * Always start the code in main() with a call to p?m_init().
 
 * Use shhopt for option processing.  i.e. call optParseOptions3().
@@ -193,8 +165,7 @@ before you read these.
   makes samples fit in a single byte and at one time was the maximum 
   possible maxval in the format.
 
-  Note that the Pnmdepth program converts an image from one maxval to
-  another.
+  Note that the Pamdepth program converts an image from one maxval to another.
 
 * Don't include extra function.  If you can already do something by 
   piping the input or output of your program through another Netpbm
@@ -203,11 +174,14 @@ before you read these.
 
   Similarly, if your program does two things which would be useful
   separately, write two programs and advise users to pipe them
-  together.  Or add a third program that simply calls the first two.
+  together.  Or add a third program that simply runs the first two.
 
 * Your program should, if appropriate, allow the user to use Standard
   Input and Output for images.  This is because Netpbm users commonly
-  use pipes.
+  use pipes.  As an alternative to Standard Input, the user should be able
+  to name the input file as a non-option program argument.  But the user
+  should not be able to name the output file if Standard Output is
+  feasible.  That's just the Netpbm tradition.
 
 * Don't forget to write a proper html documentation page.  Get an
   example to use as a template from
@@ -223,7 +197,9 @@ before you read these.
   the other hand, look the same for everyone.  Modern editors let you
   compose code just as easily with spaces as with tabs.
 
-
+* Limit your C code to original ANSI C.  Not C99.  Not C89.  Not C++.  Don't
+  use // for comments or put declarations in the interior of block.
+  Interpreted languages are OK, with Perl being preferred.
 
 
 DISCONTINUED CODING GUIDELINES
@@ -317,9 +293,11 @@ code.  Modular and structured above all.
   Especially never modify the argument of a function.  All function arguments
   should be "const".
 
-  Don't use initializers except for constants.  If you're going to set 
-  a variable twice, do it out in the open; don't hide one in the declaration
-  of the variable.
+  Don't use initializers except for with constants.  The first value a
+  variable has is a property of the algorithm that uses the variable, not of
+  the variable.  A reader expects to see the whole algorithm in one place, as
+  opposed to having part of it hidden in the declaration of the algorithm
+  variables.
 
 * Avoid global variables.  Sometimes, a value is truly global and
   passing it as a parameter just muddies the code.  But most of the
@@ -335,18 +313,18 @@ code.  Modular and structured above all.
 * Use the type "bool" for boolean variables.  "bool" is defined in Netpbm
   headers.  Use TRUE and FALSE as its values.
 
-* Do not say "if (a)" when you mean "if (a != 0)".  Use "if (a)" only if
-  a is a boolean variable.  Or where it's defined so that a zero value 
-  means ("doesn't exist").
+* Do not say "if (a)" when you mean "if (a != 0)".  Use "if (a)" only if a is
+  a boolean variable.  Or where it's defined so that zero is a special value
+  that means ("doesn't exist").
 
-* Do multiword variable names like this:  "multiWordName".  Underscores waste
-  valuable screen real estate.
+* Do multiword variable names in camel case: "multiWordName".  Underscores
+  waste valuable screen real estate.
 
-* If a variable's value is the address of something (a pointer to something),
-  it's name should reflect that, as opposed to lying and saying the value is
-  the thing pointed to.  A "P" on the end is the conventional way to say
-  "address of."  E.g. if a variable's value is the address of a color value,
-  name it "colorP", not "color".
+* If a variable's value is a pointer to something, it's name should reflect
+  that, as opposed to lying and saying the value is the thing pointed to.  A
+  "P" on the end is the conventional way to say "pointer to."  E.g. if a
+  variable's value is a pointer to a color value, name it "colorP", not
+  "color".
 
 * Put "const" as close as possible to the thing that is constant.
   "int const width", not "const int width".  When pointers to