From f75a0421bb68460a50c1d11204375ab277a8ef3d Mon Sep 17 00:00:00 2001 From: giraffedata Date: Sat, 8 May 2010 21:26:13 +0000 Subject: update git-svn-id: http://svn.code.sf.net/p/netpbm/code/trunk@1206 9d0c8265-081b-0410-96cb-a4ca84ce46f8 --- doc/Netpbm.programming | 104 +++++++++++++++++++------------------------------ 1 file changed, 41 insertions(+), 63 deletions(-) (limited to 'doc/Netpbm.programming') 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 -- cgit 1.4.1