Create Subversion repository

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

1 files changed, 200 insertions, 0 deletions

diff --git a/lib/util/shhopt.README b/lib/util/shhopt.README
new file mode 100644
index 00000000..2d241edf
--- /dev/null
+++ b/lib/util/shhopt.README
@@ -0,0 +1,200 @@
+Shhopt was originally written by Sverre H. Huseby, and extended by
+Bryan Henderson starting in March 2000 for use in Netpbm.  
+
+Below is the README file from Huseby's package.
+
+The file LICENSE.TXT in this directory contains the license (the
+Artistic License) under which Bryan took and redistributed Shhopt and
+the license under which Bryan offers the modified Shhopt to others.
+
+Bryan made the following changes to shhopt for Netpbm.  It is fully
+backward compatible with the original.
+
+- OPT_FLOAT (floating point number) data type added
+
+- optParseOptions2() added.  Advantages over optParseOptions(): You
+  can have a syntax where there is no such thing as a short option
+  (e.g. -a.  Maybe stacked like -tanp).  Then the long options can
+  have either 1 or 2 dashes (e.g. -width or --width).  Of course, -w
+  could be an abbreviation of -width; that's not the same thing as a
+  short option.
+
+- optParseOptions3() added.  Advantages over optParseOptions2(): 
+  Tells you whether (how many times, actually) an option was
+  specified - no need to play games with defaults.  Also, no need
+  to initialize an option value variable.
+
+- optStruct longName changed from char * to const char * to avoid
+  compiler warnings (with -Wwrite-strings) when you assign a string
+  literal to it (which is the normal case).
+
+- OPTENTRY/OPTENT3 macros added for declaring the option definition
+  array.
+
+- replace isdigit() with ISDIGIT() from Netpbm nstring.h so weird 
+  8-bit characters don't cause incorrect results.
+
+------------------------------------------------------------------------------
+
+
+shhopt - library for parsing command line options.
+==================================================
+
+This is a set of functions for parsing command line options. Both
+traditional one-character options, and GNU-style --long-options are
+supported.
+
+
+What separates this from traditional getopt?
+--------------------------------------------
+
+This library does more of the parsing for you. You set up a special
+structure describing the names and types of the options you want your
+program to support. In the structure you also give addresses of
+variables to update or functions to call for the various
+options. By calling optParseOptions, all options in argv are parsed
+and removed from argv. What is left, are the non-optional arguments to
+your program.
+
+The down-side of this, is that you won't be able to make a program
+where the position of the options between the non-options are
+significant.
+
+shhopt is distributed under the "Artistic license" (aka. the Perl
+license), which IMHO gives more freedom than GPL or LGPL. For a copy
+of the Artistic license, see
+
+    http://www.opensource.org/licenses/artistic-license.html
+
+For more information on Open Source licenses, go to
+
+    http://www.opensource.org/licenses/
+
+
+Usage
+-----
+
+To see how to use this library, take a look at the sample program
+example.c.
+
+A brief explanation:
+
+To parse your command line, you need to create and initialize an array
+of optStruct's. Each element in the array describes a long and short
+version of an option and specifies what type of option it is and how
+to handle it.
+
+The structure fields (see also shhopt.h):
+
+  `shortName' is the short option name without the leading '-'.
+
+  `longName' is the long option name without the leading "--".
+
+  `type' specifies what type of option this is. (Does it expect an
+      argument? Is it a flag? If it takes an argument, what type
+      should it be?)
+
+  `arg' is either a function to be called with the argument from
+      the commandline, or a pointer to a location in which to store
+      the value.
+
+  `flags' indicates whether `arg' points to a function or a storage
+      location.
+
+The different argument types:
+
+  `OPT_END' flags this as the last element in the options array.
+
+  `OPT_FLAG' indicates an option that takes no arguments. If `arg' is
+      not a function pointer, the value of `arg' will be set to 1 if
+      this flag is found on the command line.
+
+  `OPT_STRING' expects a string argument.
+
+  `OPT_INT' expects an int argument.
+
+  `OPT_UINT' expects an unsigned int argument.
+
+  `OPT_LONG' expects a long argument.
+
+  `OPT_ULONG' expects an unsigned long argument.
+
+The different flag types:
+
+  `OPT_CALLFUNC' indicates that `arg' is a function pointer. If this
+      is not given, `arg' is taken as a pointer to a variable.
+
+
+Notes
+-----
+
+* A dash (`-') by itself is not taken as any kind of an option, as
+  several programs use this to indicate the special files stdin and
+  stdout. It is thus left as a normal argument to the program.
+
+* Two dashes (`--') as an argument, is taken to mean that the rest of
+  the arguments should not be scanned for options. This simplifies
+  giving names of files that start with a dash.
+
+* Short (one-character) options accept parameters in two ways, either
+  directly following the option in the same argv-entry, or in the next
+  argv-entry:
+
+	-sPARAMETER
+	-s PARAMETER
+
+* Long options accept parameters in two ways:
+
+	--long-option=PARAMETER
+	--long-option PARAMETER
+
+  To follow the GNU-tradition, your program documentation should use
+  the first form.
+
+* Several one-character options may be combined after a single
+  dash. If any of the options requires a parameter, the rest of the
+  string is taken as this parameter. If there is no "rest of the
+  string", the next argument is taken as the parameter.
+
+* There is no support for floating point (double) arguments to
+  options. This is to avoid unnecessary linking with the math
+  library. See example.c for how to get around this by writing a
+  function converting a string argument to a double (functions
+  strToDouble and doubleFunc).
+
+
+Portability
+-----------
+
+If your libc lacks strtoul, you will need to link with GNU's -liberty,
+that may be found by anonymous ftp to ftp://ftp.gnu.org/pub/gnu/
+
+The library has (more or less recently) been compiled and `tested' on
+the following systems:
+
+	IRIX Release 5.3 IP22
+	GNU/Linux 2.2.11
+	SunOS Release 4.1.3_U1 (-liberty needed)
+	ULTRIX V4.4 (Rev. 69)
+
+All compilations were done using GNU's gcc, and GNU's make.
+
+
+Author
+------
+
+The program is written by
+
+        Sverre H. Huseby        sverrehu@online.no
+        Lofthusvn. 11 B         http://home.sol.no/~sverrehu/
+        N-0587 Oslo
+        Norway
+
+You can use and copy this for _free_, but I would be very happy if you
+send me an E-mail and tell me that you use it. If you insist on paying
+something, please donate some money to an organization that strives to
+make the world a better place for everyone.
+
+I don't like bugs, so please help me removing them by reporting
+whatever you find!
+