\input texinfo @c -*- texinfo -*-
@c %**start of header
@setfilename opt.info
@settitle opt command line parser
@c @smallbook
@c %**end of header

@include version.texi

@ignore
%** @dircategory Miscellaneous
%** @direntry
%** * opt: (opt).                           An option/parameter parsing library
%** @end direntry
@end ignore

@ifinfo
This document describes @code{opt}, v@value{VERSION}, a 
subroutine library for communicating options and
parameter values to a C program via the command line, parameter files, 
environment variables, or a rudimentary builtin interactive menu.

Copyright @copyright{} 1996,1997 James Theiler

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``Copying'' is included exactly as in the original, and
provided that the entire resulting derived work is distributed under the
terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the author.

@end ifinfo

@titlepage
@title opt 
@subtitle Options and Parameter parsing Tool
@author James Theiler (jt@@lanl.gov)

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1996,1997 James Theiler
@sp 2
This document describes @code{opt}, v@value{VERSION}, a subroutine
library for communicating options and parameter values to a C program
via the command line, parameter files, environment variables, or a
rudimentary builtin interactive menu.

The aim of the @code{opt} package is to permit programs to be both
user- and programmer- friendly.  The package attempts to
provide a direct and relatively full-featured input interface to the
ultimate user of the program, and at the same time to impose a minimal
amount of work on the programmer to "add" options parsing to
existing software.

@sp 2
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``Copying'' is included exactly as in the original,
and provided that the entire resulting derived work is distributed under
the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the author.

@end titlepage

@ifinfo
This document describes @code{opt}, v@value{VERSION}, a 
subroutine library for communicating options and
parameter values to a C program via the command line, parameter files, 
environment variables, or a rudimentary builtin interactive menu.
@end ifinfo

@node    Top, Nutshell, (dir), (dir)

@menu
* Nutshell::                    What is opt, in a nutshell?
* Opt::                         What is opt, in a deeper philosophical sense?
* Etc::                         What else?
@end menu

@node    Nutshell, Opt, Top, Top
@chapter Nutshell

@code{opt} is a subroutine library which facilitates the
convenient input of parameters 
to a C program.  Parameters are parsed
from a command line, with further facilities for reading options from
files, from environment strings, or from an interactive environment.

The aim of the @code{opt} package is to permit programs to be both
user- and programmer- friendly.  The package attempts to
provide a direct and relatively full-featured input interface to the
ultimate user of the program, and at the same time to impose a minimal
amount of work on the programmer to "add" options parsing to
existing software.

@code{opt} is similar in its effects to the standard UNIX (and also to
the GNU) @code{getopts} packages, and I have tried (though possibly not
as hard as I could have) to keep them as similar as possible whenever
feasable.  But @code{opt} does takes a somewhat different philosophy.
Variables are "registered" to strings, and whenever the strings are 
used on the command line, the variables are updated accordingly.
This tends to be a little more compact (and in my view
more convenient) than the loop and case-statement approach used by
@code{getopt}.  Also, @code{opt} has a few more bells and whistles.

@menu
* What the user sees::          How to use programs that use opt
* What the programmer sees::    How to write programs that use opt
@end menu

@node   What the user sees, What the programmer sees, Nutshell, Nutshell
@section What the user sees

Code written with @code{opt} can read parameters from the command line;
for example running the program
@example
birthday -m 9 -d 11 -y1989 -v
@end example
@noindent
can set paramters @var{month}=9, @var{day}=11, and @var{year}=1989,
and also turn on the @var{verbose} flag,
inside the @code{birthday} program.  Note that the space between
the single-character option name and the value is optional.
Some parameters can also be set using
long names, for instance:
@example
birthday --month=9 --day 11 -y1989 
@end example
@noindent
Note that the @samp{=} can only be used with 
the long form of the options, but it is optional and white space can
also be used to separate the option name from its value.  Note also
that the long name @samp{--month} and the variable name @var{month}
only happen to be the same in this example; they aren't in general.
Alternatively, you can use
@example
birthday @@file.opt
@end example
@noindent
to read the paramters from the file @file{file.opt}.  There is also an 
interactive menu.  If you type
@example
birthday --menu
@end example
@noindent
at the command line, then you'll see this on the screen:
@example
birthday
m Month                                    4
d Day of month                             24
y Year                                     1993
v Verbose                                  FALSE
p Use Pade Approximants                    FALSE
g Gregorian                                FALSE    
(Type ? for Help)
-> 
@end example
@noindent
By invoking the menu, the user is able to see what all the available
options are, even the obscure ones.
The prompt @samp{->} is waiting for your response; type @samp{m 9} and
return to set the value of @var{month} to 9.  Set any other parameters as
you see fit.  Enter a blank line, and the you'll again see a list of 
parameters and values.
Then type @samp{=} and the program will run with those
parameters, and then return to the prompt.  You can change the parameters
and run again if you like.  Type @samp{.} to exit.

Finally, the program is somewhat self-documenting.  Type
@example
birthday --help
@end example
@noindent
at the command line, and
then you'll see a message like this:
@example
Usage: birthday [options]
To invoke the menu, type:
        birthday --menu
The options are:
 -m, --month        <integer>       Month
 -d, --day          <integer>       Day of month
 -y                 <integer>       Year
 -v                 <flag>          Verbose
 -p                 <flag>          Use Pade Approximants
 -g                 <flag>          Gregorian  @end example
@noindent
and then the program exits.  There are several other features provided
by @code{opt} that will be discussed in later sections.

@node    What the programmer sees,  , What the user sees, Nutshell
@section What the programmer sees
The above example is based on actual output from the following code.
This is not the simplest possible, but it illustrates what I personally
find to be the most commonly used features.  More sophisticated options
processing is also available, and will be discussed in later sections.
@example
/* birthday.c */

#include <stdio.h>
#include <opt.h>                /* part of opt package */

/* Parameters that user has access to via opt package;
 * They are typically (but not necessarily) global variables.
 * Their default values are provided in the assignement statements.
 */
int month=9;
int day=11;
int year=1989;
int verb=0;
int pade=0;
int greg=0;

/* All of what the program itself does is in the birthday() function;
 * This function does what a non-options parsing main() might do.
 */
int birthday(int argc, char **argv)
@{
    if (month == 9 && day == 11 && year == 1989)
        printf("Happy birthday, Max\n");
    else if (month == 4 && day == 24 && year == 1993)
        printf("Happy birthday, Sky\n");

    if (verb)
        printf("Hello, world: %4d/%02d/%02d\n",year,month,day);

    return OPT_OK;
@}

/* all of the options parsing is in the new main() function */

int main(int argc, char **argv)
@{
    /* optrega() registers short name '-m' and long name '--month' to
     * variable 'month', and provides brief description "Month"
     */
    optrega(&month,OPT_INT,'m',"month","Month");
    optrega(&day,  OPT_INT,'d',"day",  "Day of month");
    /* optreg() only provides short name '-y' */
    optreg(&year,OPT_INT,'y',"Year");
    /* register some flag variables... */
    optreg(&verb,OPT_FLAG,'v',"Verbose");
    optreg(&pade,OPT_FLAG,'p',"Use Pade Approximants");
    optreg(&greg,OPT_FLAG,'g',"Gregorian");

    /* the function birthday() is registered with opt */
    optMain(birthday);

    /* opt() is the routine that actually parses the argc/argv
     * variables
     */
    opt(&argc,&argv);
    /* and when it's done, argc/argv will contain the leftover
     * argc/argv variables, including the same argv[0] as in
     * the original argc/argv
     */

    /* Now that variables are parsed, run birthday() */
    return birthday(argc,argv);
@}
@end example

The opt package consists of the header file @file{opt.h}, which must be
@code{#include}'d in any code that uses opt, and the library file 
@file{libopt.a}, which is linked to the program at compile time
@example
        cc -Idir_with_opt_h -Ldir_with_libopt_a birthday.c -lopt
@end example

@node Opt, Etc, Nutshell, Top
@chapter Opt

@menu
* Philosophical digression::    
* What is Opt::                 
* User Interface::              
* Programmer Interface::        
@end menu

@node Philosophical digression, What is Opt, Opt, Opt
@section Philosophical digression

Programs that provide a convenient user interface,
especially those with gooey user interfaces (GUI's), generally require a fair
bit of programming to produce.  But for short programs that will not be
used a lot, "programmer friendly" is more important than "user
friendly."  If a program grows in size or usefulness, the programmer
can then go back and put in a better interface.  But in doing so,
the programmer trades
away the "programmer friendliness" of the original code to end up with
software that exhibits "user friendliness".

Suppose you want to write a program that depends on some parameters.
As a programmer, it is convenient to set the parameters (in the
vernacular, to "hardcode" them) to desired values right in the program.
It is not really very convenient, though, because you have to recompile the
program every time you want to run it with different values.  This is
especially inconvenient when the user and the programmer are different
people.

It is usually more convenient (for the user) if the parameters can be
specified at run time.  There
is, of course, more than one way to do this.  You can specify parameter
values in an input file, for instance.  Then the program has to open the
file, read the values, assign them to the appropriate variables, and
then compute accordingly.  It's a little inconvenient for the
programmer, and a little inconvenient for the user, but if there are a
large number of parameters, this is often the best approach.  Even for
a small number of parameters, it is useful to at least have the option
of saving parameter values in a file.

Another approach is to have the program "ask" the user what parameter
values are desired.  After typing @samp{birthday} for instance, the
program might respond with
@example
What is the number of the month?_
@end example
@noindent
to which the user would reply, say, "9".  Then
@example
Enter the day of the month and the year?_
@end example
@noindent
to which the user would type "11 1989" or perhaps "11,1989" depending
on the format that the program expected for input.  This style of
program sometimes seems friendly at first, since the user doesn't
have to know a lot about the program to run it, but just has to answer the
questions.  It can get to be pretty awkward after awhile, though,
particularly if there are a lot of
options, and especially if the program is to be used in shell scripts.  
It is not too hard to write the program to do this (it is basically a 
series alternating @code{printf}'s and @code{scanf}'s),
but for a lot of parameters, it can get pretty tedious.

One of the most popular approaches is to 
specify the options and parameter values directly from the command line.
The user types
@example
birthday -m 9 -d 11 -y 1989
@end example
@noindent
and this specifies in one compact line values for month, day, and year.
This is a bit of a compromise; the user has to know what all the options
are, and the programmer has to do a little string parsing.  The motivation
for the @code{opt} package is to bridge this gap: to on the one hand
simplify the programmer's task of converting command line strings into
parameter assignments, and on the other hand to provide the user a little
more information about the available options and a little more convenience
in setting those options and parameter values.


@node What is Opt, User Interface, Philosophical digression, Opt
@section What is Opt?

I know I've said this already, but@dots{}
@code{opt} is a subroutine library for communicating options and
parameter values to a C program via the command line, parameter files, 
environment variables, or a rudimentary builtin interactive menu.

The aim of the @code{opt} package is to permit programs to be both
user- and programmer- friendly.  The package attempts to
provide a direct and relatively full-featured input interface to the
ultimate user of the program, and at the same time to impose a minimal
amount of work on the programmer to "add" options parsing to
existing software.

The next sections basically parallel the @file{Nutshell} chapter, but
add a little more detail.
First, the @code{opt} interface will be described, as it appears to the user.
This comprises the advertisement for incorporating @code{opt} into your code.
Then it will be shown how to write code that uses @code{opt} for its user
interface.

@menu
* User Interface::
* Programmer Interface::
@end menu

@node User Interface, Programmer Interface, What is Opt, Opt
@section User Interface

Currently, @code{opt} supports the following modes of interface to the user:

@itemize @bullet
@item Direct command line options
@item Options from a named file   
@item Environment strings
@item Rudimentary builtin menu
@item Standard usage messages
@end itemize

@menu
* Direct command line options::  
* Options from a named file::   
* Environment strings::         
* Rudimentary builtin menu::    
* Standard usage messages::     
@end menu

@node Direct command line options, Options from a named file, User Interface, User Interface
@subsection Direct command line options
Options are typically invoked with a delimiter (either @samp{-} or @samp{--})
followed by an alphabetic character or string, and both of those by the value of
the parameter.  Thus @samp{birthday -m5} means that the parameter associated
with @samp{m} takes the value 5.  The same effect is acheived by @samp{birthday
-m 5} (with a space between @samp{m} and @samp{5}).
The power of this assignment is that options for
several parameters can be assigned in a flexible way:
@example
birthday -m9 -d11 -y1989  ;@i{Sets values of month, day, and year}
birthday -d11 -y1989 -m9  ;@i{Doesn't matter what order}
birthday -m9              ;@i{Set month=5, day and year to their defaults}
birthday -m 9             ;@i{Space is permitted between m and 9}
birthday - m9             ;@i{Not valid to have space beweeen - and m}
birthday -m9-d11          ;@i{Not valid; need space between each}
                          ;@i{delimited option}
@end example

Some kinds of options are of a different form.  Among these are "flags"
which signal whether a given option is on off.  Thus, one might signal
that a program is to operate in verbose mode with a command line of 
the form @samp{birthday -m9 -v}.  
Alternatively, one can write @samp{birthday -m9 -v+} to explicitly
turn the verbose option on, or @samp{birthday -m9 -v-} to explicitly turn
verbose off.  Unlike options which assign values, flag parameters can be
assigned with a single delimiter.  Thus, one might have a verbose (@samp{v})
flag, a gregorian (@samp{g}) flag, and a "use Pade approximant"
(@samp{p}) flag.  In this case, one can write commands of the
following forms:
@example
birthday -v -g -p  ;@i{Invoke all flags}
birthday -vgp      ;@i{Invoke all flags, in a more compact notation}
birthday -pv+g-    ;@i{Invoke p-flag, while explicitly}
                   ;@i{turning v-flag on, g-flag off.}
@end example
Invoking a flag is not always the same as setting the flag to ON. 
Depending on how the flags are defined in the program, invoking a
flag may set its value to ON, to OFF, or toggle it to the opposite of
its value before invocation.  For instance, if the @samp{p}-flag is a toggle,
the command @samp{birthday -p -m9 -p} toggles it twice, so that the effect of
the two invocations are to cancel each other out.  The motivation for toggles
and other kinds of flags will become apparent when the command line is
extended to files and environment variables and interactive menus.

@node Options from a named file, Environment strings, Direct command line options, User Interface
@subsection Options from a named file

It is clear that a program with many options begins to get unwieldy on
the command line, and it is desirable to save options in a file, and not
have to retype them every time the program is run.  The @code{opt}
package permits this with command lines of the form @samp{birthday
@@bday.opt}.  Here @file{bday.opt} is a file which contains options
which are used by the program @code{birthday}.  The form of the options file
@file{bday.opt} is like that of the command line itself.  Thus, if the file
is composed of the string @samp{-m9 -d11 -y1989 -vg} then it is as if that string
replaced @samp{@@bday.opt} on the command line.

A file permits some luxuries that are not available on the command line
directly.  One of these is that you are not limited to a single line, and
another is that you can add comments in the file.  Thus if the file looks
like this:
@example
;file: bday.opt
;Comments are preceded by a semi-colon
-m9             ;September
-g              ;Use gregorian
-d11 -y1989     ;Can still have several options on one line
@end example
@noindent
Then @samp{birthday @@bday.opt" is exactly equivalent to "birthday -m9 -g -d11 -y1989}.

It is possible to mix direct command line options with file options.  Thus
@samp{birthday -v @@bday.opt -p} is equivalent to 
@samp{birthday -v -m9 -g -d11 -y1989 -p}.  This is particularly useful if you
want to make many runs in which only a few parameters are changed at a time.
For instance, 
@example
birthday @@defaults.opt 
birthday @@defaults.opt -m10
birthday @@defaults.opt -v
@end example
@noindent
might represent three runs of the program "birthday", the first with a
default set of options, the second with the same options except m=10,
and the third the same as the first, except that verbose is turned ON.

It is also possible to nest files, so that one might have two files:
@example
;file: bd1.opt
-m5             ;set some option values
-y 1997
@@bd2.opt        ;get more options from file bd2.opt
@end example
@noindent
and
@example
;file: bd2.opt
-d 11           ;set day=11
-y 1989         ;set year=1989
@end example
@noindent
and then the command line @samp{birthday @@bd1.opt} conceptually expands to be
the equivalent @samp{birthday -m5 -y 1997 -d 11 -y1989}.  This is a completely
valid command line, even though the 'y' option appears twice; it is 
the last value of a variable which the program uses, in this case y=1989.

Of course, recursive nesting will only get you into trouble.    

There is a useful abbreviation for files: @@@@ stands for the
default options filename which is always the program name with the
extension ".opt".  Thus @samp{birthday @@@@} is equivalent to 
@samp{birthday @@birthday.opt}

You can also write to an @code{opt} file; the directive @samp{%file.opt}
writes the current options to the file @file{file.opt}.  Here, @samp{%%},
invoked for a program called @samp{birthday}, is an 
abbreviation for @samp{%birthday.opt}.

@node Environment strings, Rudimentary builtin menu, Options from a named file, User Interface
@subsection Environment strings

The program which uses the @code{opt} package can be instructed to look for
an environment variable for options.  If birthday sets @samp{BIRTHDAY} as its
option environment variable, and if the environment string
@samp{BIRTHDAY=-m9 -y1989}
is set, then running @samp{birthday} is equivalent to running @samp{birthday -m9
-y1989}.  The environment options are assigned before any command line
options, so they can be over-ridden: thus the command @samp{birthday -m10}
resets m to be equal to 10 instead of m=9 suggested by the
environment string, but one still has y=1989.  The environment string
is therefore a useful place for storing default options that you
don't want to have to keep typing them each time you run the
program.  In the UNIX C-shell you can set an environment string with the 
@samp{setenv} command:
@example
setenv BIRTHDAY "-m9 -y1989"
@end example
while in the Bourne shell, you'd write
@example
BIRTHDAY="-m9 -y1989"
export BIRTHDAY
@end example
Note that UNIX
environment strings are not the same thing as shell variables
In MS-DOS, one uses the command "set";
the format is
@example
set BIRTHDAY=-m9 -y1989
@end example
@noindent
with no quotes.  To unset, type "set BIRTHDAY=", and to view just type
"set".  (However, it's been ages since I've used @code{opt} on MS-DOS;
I'd be surprised if it still worked on that platform.  Of course I'm
always surprised when anything works on that platform.)

@node Rudimentary builtin menu, Standard usage messages, Environment strings, User Interface
@subsection  Rudimentary builtin menu

Although the above methods provide flexible means of getting parameter
values to a program which is run in background or batch mode, it is also
useful to alter parameters interactively.  The @code{opt} package provides
a convenient way to do this, with an interactive menu.
To invoke the menu type @samp{$} (or @samp{--menu})
at the end of the command line. For instance,
typing @samp{birthday -m4 -y1993 $} will return a menu that looks something like
@example
birthday
m Month                                    4
d Day of month                             11
y Year                                     1993
v Verbose                                  FALSE
p Use Pade Approximants                    FALSE
g Gregorian                                FALSE
(Type ? for Help)
-> 
@end example
The prompt @samp{->} is an invitation to the user to write a segment of a
command line.  For instance a reply of @samp{-m4 -vg} will come back 
with a bare prompt:
@example
->
@end example
@noindent
Responding with an empty line will give a new menu that looks like
@example
m Month                                    4
d Day of month                             11
y Year                                     1989
v Verbose                                  TRUE
p Use Pade Approximants                    FALSE
g Gregorian                                TRUE
(Type ? for Help)
-> 
@end example
When you are ready to run the program with these values, type @samp{=}.
Actually, there are a number of things you can type at the command
prompt; type a plain @samp{?} for the following description:
@example
        - Options delimiter   
        ? Help                
        = Run program and return to menu
        ! Shell to Operating System
        $ Exit menu           
        + Additional options  
        @@<filename> Get options from file
        @@@@ Get options from file [birthday.opt]
        %<filename> Put options in file 
        %% Put options in file [birthday.opt]
        . Quit                
-> 
@end example

It is also possible that @samp{?c} will give further information
about the option specified by @samp{c}, although this requires that
the programmer supplied extra information (usually, the brief description
is all that is available).  For example,
@example
        -> ?d
        d: Use day of month, should be less than 32
        ->
@end example

@node Standard usage messages,  , Rudimentary builtin menu, User Interface
@subsection Standard usage messages
The user can type
@example
birthday --help
@end example
@noindent
and get a fairly complete usage message:
@example
Usage: birthday [options]
To invoke the menu, type:
        birthday --menu
The options are:
 -m, --month        <integer>       Month
 -d, --day          <integer>       Day of month
 -y                 <integer>       Year
 -v                 <flag>          Verbose
 -p                 <flag>          Use Pade Approximants
 -g                 <flag>          Gregorian
@end example


@node Programmer Interface,  , User Interface, Opt
@section Programmer Interface

First an example source code will be shown so that the programmer
gets an idea of what it takes to incorporate @code{opt} into his
or her favorite application.  Subsequent sections will then go into
more detailed explanation.

@menu
* Example code::                
* Registering options::         
* Setting some strings::        
* Registering functions (hooks)::  
* Misc::                        
@end menu

@node Example code, Registering options, Programmer Interface, Programmer Interface
@subsection Example code

The easiest way to see how to use the @code{opt} package is with an
example.  The following program illustrates most of the features that
you'd actually want to use (and several you probably don't care about).

@example
/* testopt.c */

#include <stdio.h>
#include <stdlib.h>
#include <opt.h>

int month=4;
int day=24;
int year=1993;
char *who=NULL;

int go(int argc, char **argv)
@{
    if (argc>1) @{
        printf("In program %s, Extra option: %s\n",argv[0],argv[1]);
    @}

    if (optinvoked(&month)) @{
        printf("User set month...\n");
    @}

    if (month == 9 && day == 11 && year == 1989) @{
        printf("Happy birthday, Max\n");
    @} else @{
        printf("Hello, %s: %4d/%02d/%02d\n",(who==NULL ? "world" : who),
               year,month,day);
    @}
    return OPT_OK;
@}

int checkyear(void *v)
@{
    if (year == 2000) @{
        printf("Watch out for that year=2000 bug!\n");
        return OPT_ERROR;
    @}
    return OPT_OK;
@}
int quit()
@{
    printf("Bye...\n");
    return OPT_OK;
@}
int write_version()
@{
    printf("Version XXX\n");
    optExitNumber(12);
    return OPT_EXIT;
@}
int fix_mon(void *v)
@{
    int m;
    /* fix whatever int variable v is pointing to */
    m = *((int *)v);
    if (m < 1 || m > 12) 
        m=1;
    *((int *)v) = m;
    return OPT_OK;
@} 

main(int argc, char **argv)
@{
    optreg(&month,OPT_INT,'m',"Month");
    optlongname(&month,"month");
    opthook(&month,fix_mon);

    optrega(&day,OPT_INT,'d',"day","Day");
    opthelp(&day,"Use day of month, should be less than 32");
    
    optreg_INT(&year,'y',"Year");
    optreg(&year,OPT_INT,'Y',"Year");
    optdescript(&year,"What Year");
    opthook(&year,checkyear);

    optreg(&who,OPT_UNDELIM,'\0',"Who to say hello to");

    optexec("version",write_version,"Write version number and exit");

    optEnvVarName( "OPT" );
    
    optMain(go);
    optQuit(quit);

    opt(&argc,&argv);
    return go(argc,argv);
@}



@end example


@node Registering options, Setting some strings, Example code, Programmer Interface
@subsection Registering options

	It is necessary for the programmer to somehow tell the package
which options are associated with which variables in the program, and
what descriptions @code{opt} should use in the usage message and the menu.
This is done with a function call that "registers" (or associates@footnote{
When I say "register" I mean it as a verb, 
in the sense of "register your handgun",
and not as a noun, meaning an immediate memory location on a microprocessor.
I apologize to any old assembler-coders who may find this language confusing.
I do not apologize to the NRA-types who oppose global variables and
unregulated firearms.})
a variable and a name.  These functions (one for each variable, in general)
are usually called at the beginning of the code.  For example,
@example
    optreg(&day,OPT_INT,'d',"Day");
@end example
@noindent
where @var{day} is the name of the variable as it appears (for
instance as a global variable) in the C program; @var{OPT_INT} tells
opt that the variable is an @samp{int}, @var{d} is the alphabetic 
character that is used on the command line to alter the parameter
@var{day}, and @var{"Day"} is a string that will be used in the 
menu and the standard usage messages.

You can register a long (string) name as well as the short (one character) 
name.  The function name has an extra @samp{a} (mnemonic: all) at the end.
@example
optrega(&month,OPT_INT,'m',"month","Month");
@end example
With this registration in place, @samp{-m 4} and @samp{--month=4} have the same
effect; to change the value of the variable @var{month} to four.
If you want to register a long name to a variable without also 
having a short name (this is sometimes desirable if there are a 
lot of options), this can be done with a call to @samp{optrega} that
sets the short name to the null character; e.g.,
@example
optrega(&month,OPT_INT,'\0',"month","Month");
@end example

The variable @code{OPT_INT} is of type @samp{opt_TYPE}; this is an enumerated type
and is defined in the header file @file{opt.h}.  The available option
types are: @code{OPT_INT}, @code{OPT_SHORT},
@code{OPT_LONG}, @code{OPT_CHAR},
@code{OPT_UINT}, @code{OPT_USHORT},
@code{OPT_ULONG}, @code{OPT_UCHAR},
@code{OPT_INTLEVEL}, @code{OPT_FLOAT}, @code{OPT_DOUBLE}, @code{OPT_FLAG},
@code{OPT_NEGFLAG}, @code{OPT_ABSFLAG}, @code{OPT_ABSNEGFLAG}, 
@code{OPT_STRING}, @code{OPT_CSTRING}, 
@code{OPT_UNDELIM}, and @code{OPT_UNDELIMC}.
There is also a type @code{OPT_NUL} that is used internally.

Most of these are self-explanatory: 
@example
OPT_INT     int
OPT_SHORT   short int
OPT_LONG    long int
OPT_UINT    unsigned int
OPT_USHORT  unsigned short int
OPT_ULONG   unsigned long int
OPT_FLOAT   float
OPT_DOUBLE  double
@end example
All of these are invoked on the command line with the form @samp{-x#}
or with @samp{-x #} where @samp{#} is the value of the number.  Along these same
lines is the type
@example
OPT_CHAR    char
@end example
which can only be invoked as @samp{-x#} and not @samp{-x #}.  
The latter form will
assign the @var{x} variable to the character value NULL ('\0'), 
and @samp{#} will be
treated as the next option.

There are a variety of flags:
@example
OPT_FLAG        int     @i{This is a toggle-type flag, whose first}
                    @i{invocation makes the flag TRUE (or ON).}
OPT_NEGFLAG     int     @i{When flag is TRUE, variable is FALSE.}
OPT_ABSFLAG     int     @i{No toggle.  Any (nonzero) number of }
                    @i{invocations makes this flag TRUE.}
                    @i{In my own experience, I have found absolute flags 
        are usually preferable to toggle flags (and now I wish I'd made
        absolute flags the default.  The problem with toggles is
        that you can easily lose track of what the current state
        of the toggle is, especially when options can be specified
        in files, environment variables, and the menu, as well as
        the command line itself.}
OPT_ABSNEGFLAG  int     @i{Any invocation makes flag FALSE.}
OPT_INTLEVEL    int     @i{This is a kind of a combination flag and}
                    @i{int: it is an integer that can take on}
                    @i{only positive values, usually less than}
                    @i{ten.  I find this useful for "verbose"}
                    @i{since I can not only turn verbose ON,}
                    @i{but I can have a range from slightly}
                    @i{verbose to extremely verbose.}
                    @i{For this flag, each invocation increases}
                    @i{the level; eg, "-v -v" sets verbose=2.}
                    @i{and -v- turns verbose off.}
@end example
There are two types of strings, variable and constant.  Which of
these to use depends on how the variable is declared:
@example
char *vstring=NULL;     /* variable string */
char cstring[80];       /* constant string */
char *cstring="hello";  /* this is a constant string too */
@end example
@noindent
The difference is that @var{cstring} already has space allocated for it,
so to have @var{cstring} be "string" one has to use @samp{strcpy(cstring,"string")},
and note that the pointer @var{cstring} itself does not change.  By contrast,
to use @var{vstring}, space must be allocated dynamically.  In this case,
one has to change the value of the pointer @var{vstring} with something like
@example
vstring = (char *)malloc(strlen("string")+1);
strcpy(vstring,"string");
@end example
@noindent

@example
OPT_STRING         char *
OPT_CSTRING         char *
@end example
@noindent
By the way, if you are using @samp{OPT_CSTRING}, you should make sure
that it has room for a string of length @samp{OPT_MAXSTRLEN}.  But in
general, you should prefer @samp{OPT_STRING} of the two.  (Note, 
@samp{OPT_STRING} used to be called @samp{OPT_VSTRING} but the latter
form is now discouraged.)

Finally, undelimited strings which do not have an alphabetic character
identifier (@i{e.g.,} invoked as @samp{program "string"} instead of 
@samp{program -s "string"}) can be read from the command line and into
a variable using one of these two types:
@example
OPT_UNDELIM         char *
OPT_UNDELIMC        char *
@end example
@noindent
@code{OPT_UNDELIM} and @code{OPT_UNDELIMC} are the same as 
@code{OPT_STRING} and @code{OPT_CSTRING}, 
except that they are invoked on a command line without a delimeter.

If a variable is registered, then you can change or add to its attributes;
for instance:
@example
optreg(&var,OPT_INT,'c');
optlongname(&var,"variance");
@end example

The various registration functions (@samp{optreg()}, etc) return
an integer which is the index of the registered option. Sometimes (eg,
instance when there is no variable associated with the registration)
this integer is a more useful identifier of a given option.
The above, for instance, is equivalent to:
@example
n = optreg(&var,OPT_INT,'c');
optlongname_n(n,"variance");
@end example

@table @code
@item void optchar(void *v, char c)
Associates the single-character name with the variable pointed to by @var{v}.
@item void optchar_n(int n, char)
Associates the single-character name with the @var{n}'th registered variable.

@item void optlongname(void *v, char *longname)
Associates the long name to the variable pointed to by @var{v}.
@item void optlongname_n(int n, char *longname)
Associates the long name to the @var{n}'th registered variable.

@item void optdescript(void *v, char *descript)
Changes the brief description of the variable pointed to by @var{v}.
@item void optdescript_n(int n, char *descript)
Changes the brief description of the @var{n}'th registered variable.

@item void opthelp(void *v, char *help)
Associates a longer help string with the variable pointed to by @var{v}.  
This is the string the user will see upon typing @samp{?c}
at the menu prompt, where @samp{c} is the single-character name.
@item void opthelp_n(int n, char *help)
Associates a longer help string with the @var{n}'th registered variable.  
@end table




@node Setting some strings, Registering functions (hooks), Registering options, Programmer Interface
@subsection Setting some strings

The following functions set strings which the @code{opt} package uses
for various things.
@table @code
@item void optUsage(char *s)
Sets the usage statement that the program will print as part
of the help message.

@item void optTitle(char *s)
Sets the title, which appears as the first line in the menu.
If not set, then the program name is used.

@item void optEnvVarName(char *s)
Sets the name of the environment variable where
the @code{opt} package will look for initial command line options.
If not set, the @code{opt} will not be check any environment variable
for options processing.

@item void optDefaultString(char *s)
The program itself can define a default command line
to be processed before the environment string and before
the actual command line.  To be honest, I can't imagine when
you'd want to use this in real life.

@item void optDefaultFile(char *s)
The program can define a file name, eg @samp{~/.programrc} or 
@samp{/etc/program.opt}, in which to look for default options
for the program.  If the file exists, then its options are read
in before reading the environment string or the command line.

@item void optExitNumber(int n)
If opt has to exit, then call exit(n);

@end table

@node Registering functions (hooks), Misc, Setting some strings, Programmer Interface
@subsection Registering functions (hooks)

Hooks are means by which the user can write routines which 
the @code{opt} package calls during its processing.  This enables the
programmer to customize the behavior of @code{opt} to the program at
hand.  Of course @code{opt} has to be informed of the function
(in the same way that variables have to be registered, so do
functions).  The hook function should always return an integer,
and a value of zero
is the default that tells @code{opt} that all is okay.  (You can also 
return @samp{OPT_OK}, which is defined to be zero in @file{opt.h}.)
The return value tells @code{opt} what to do after the hook has
been run.  [** Warning: I am thinking of changing these. --jt **]
@table @code
@item OPT_OK
Default.  Keep processing options.
@item OPT_ERROR
Signals to @code{opt} that the hook was not successful.  Currently,
@code{opt} doesn't do anything differently from what it does if
@samp{OPT_OK} is returned.
@item OPT_EXIT
Program exits using the C command @samp{exit(n);} The value of n will
be zero unless it has been set by the function @samp{optExitNumber(n)}.
@item OPT_QUIT
Program exits, as with @samp{OPT_EXIT}, but it will first check to see if
a quit-hook has been defined with the @samp{optQuit()} function.  If one has, 
then it will run the quit-hook and then exit.
@item OPT_ABORT
If you are in the
menu, you should be returned to the prompt (assuming you configured @code{opt}
to @samp{--enable-longjmp} (default) at compile time); but if you are running
from the command line, the program will quit calling a quit-hook if
one has been defined.
@end table

There are basically two kinds of hooks.  The first kind is associated
with a specific variable, and it is run whenever that option is invoked.
These hooks take a single argument, a @samp{void *} that points to the
associated variable.  The second kind of hook is not associated with
a specific variable, and it takes no arguments.  It might be associated with
a command line string (such as @samp{--version} which you might want to use to
make the program write a version number and exit), or with the general
behavior of @code{opt}, such as the quit hook described below.
Here, @samp{OPT_PFI} is declared @samp{typedef int (*OPT_PFI)()} 
in the header file @file{opt.h}; it is a pointer to 
a function returning an integer. 
(Currently we exploit C's loose typecasting
rules, so that @samp{OPT_FPI} refers to a function with any number 
of arguments, as
long as it returns an integer.  In future versions, we may define
@samp{OPT_PFI_V} and @samp{OPT_PFI_ARG} types, to indicate functions
that take arguments @samp{void *} and @samp{int,char **} respectively.)

The first kind of hook is registered with the function @samp{opthook()}.
For instance, if you register a hook
with a statement such as
@example
int fix_mon(void *v) @{ ... @}
int month=9;
...
optreg(&month,OPT_INT,'m',"Month");
opthook(&month,fix_mon)
@end example
then the function @samp{fix_mon} will be called when the 'm' option 
is invoked.  For instance, the
function might determine whether the integer @var{month} variable
was between 1 and 12, and if not, to fix it in some way.
Note that the hook function @samp{fix_mon} takes a single @samp{void *} 
argument; when @code{opt} calls the hook function, it will use a
pointer to the variable @var{month} as the argument.
You can use the argument to get (and manipulate) the value of the
variable @var{month}.  However, if the variable is global, then you
can also manipulate the month directly.  So the following two
examples serve the same purpose.
@example
int fix_mon(void *v) 
@{
    /* don't bother using the argument v; 
     * just manipulate month directly */ 
    if (month < 1 || month > 12) 
        month=1; 
    return OPT_OK; 
@}
@end example
and
@example
int fix_mon(void *v)
@{
    int m;
    /* fix whatever int variable v is pointing to */
    m = *((int *)v);
    if (m < 1 || m > 12) 
        m=1;
    *((int *)v) = m;
    return OPT_OK;
@} 
@end example
The second example is not as pretty to look at, but it is more general.
It does not have to know which variable it is fixing, and in fact you
can @samp{opthook} this function to several variables, and it will 
apply the @samp{fix_mon} algorithm to those variables as they are invoked.

@table @samp
@item void opthook(void *v, OPT_PFI fcn)
associates a hook @samp{fcn} with the variable pointed to by @var{v}.
Whenever the option associated with @var{v} is invoked, 
eg from the command line, the hook is called.
@item void opthook_n(int n, OPT_PFI fcn)
associates a hook @samp{fcn} with the @var{n}'th option.  @var{n}
is the value returned by the registration function @samp{optreg}.
@item int optexec(char *longname, OPT_PFI fcn, char *descript)
associates a hook @samp{fcn} to the string pointed to by @var{longname}.
For instance, the command 
@samp{optexec("version",print_version,"Write version info and exit");}
will cause the function @samp{print_version()} to be called whenever
the string @samp{--version} appears on the command line.  The function 
@samp{print_version()} takes no argument, and depending on
its return value, the program will either exit or keep going after
printing the version string.

@item optMain(OPT_PFI fcn)
The most commonly used hook in an @code{opt} program, at least by me.
This function is run when the user types @samp{=} at the @code{opt}
menu prompt.  Usually, the programmer writes @samp{fcn(argc,argv)} to do
whatever it is that the program is supposed to do (essentially
the same as @samp{main(argc,argv)} but without the command line parsing
that @code{opt} is taking care of).  The arguments @samp{argc,argv}
that @samp{fcn} sees are the command line strings that are "leftover"
after @code{opt} has finished parsing; @samp{argv[0]} is retained however,
so that @samp{fcn} behaves just like a @samp{main} function would behave.
When @samp{fcn} is finished, you will be returned to the command
line prompt.  If @code{opt} was configured at compile time with the
@samp{--enable-longjmp} (default), then if you interrupt (^C) 
@samp{fcn} while it is running, 
you will be returned to the command prompt (instead of exiting
the program completely).

@item optRun(OPT_PFI run)
This is essentially the same as @samp{optMain}, except that the
function @samp{run()} takes no arguments.  If you set this hook
and the hook in @samp{optMain}, then this hook will be ignored.  
@item optQuit(OPT_PFI fcn)
is a hook that is run just before the program that is using
@code{opt} exits.

@item optAdditionalUsage(OPT_PFI fcn)
This hook is run at the end of the usage message, and can be used
to provide the user with additional usage information.

@end table

@node Misc,  , Registering functions (hooks), Programmer Interface
@subsection Misc
@table @code
@item int optinvoked(void *v)
Returns the number of times the option associated with the variable
pointed to by @var{v} was invoked by the user.  
@end table

@node Etc,  , Opt, Top
@chapter Etc

@menu
* Installation::                
* recipe::                      
* Global variables::            
* Single file::                 
* Extensions::                  
* Bugs::                        
* Warranty::                    
* Copying::                     
@end menu

@node Installation, recipe, Etc, Etc
@section Installation

Because @code{opt} does not require exotic systems services or
esoteric libraries, installation on a variety of platforms should
be straightforward.  What follows is a guide to installing OPT on
a UNIX system, but I have heard of at least one successful
install on a Microsoft operating system.

First you have to un-archive the @file{opt-XXX.tar.gz} file, 
where @samp{XXX} is the version number, using commands along these lines:
@example
           gzip -d opt-XXX.tar.gz
           tar xvf opt-XXX.tar
           cd opt-XXX
@end example

Then, it's bascially a generic GNU installation, with @code{configure}, 
@code{make}, and @code{make install}.  More details can be found in the 
@file{INSTALL} file that should be in the distribution, but those are 
details about the generic installation procedure, and contain no 
@code{opt}-specific notes.

@enumerate
@item You configure with the command
@samp{./configure} where the initial @samp{./} is to ensure that you are 
running the 
configure script that is in the current directory.
You can also use the configure command with options.  Type 
@samp{./configure --help}
to see what those options are.  One of the most useful is the
@samp{--prefix=PATHNAME}
option, which tells you where to install it.  
Some @code{opt}-specific 
options are:
@table @samp
@item --disable-longjmp
If @code{longjmp} is enabled (default), then hitting @samp{^C}
during a run launched from the menu prmopt will return you to the menu prompt;
if @code{longjmp} is disabled, then @samp{^C} exits the program entirely.
You should only disable longjmp if you have trouble compiling.
@item --with-readline
If your system has @code{GNU readline} installed@footnote{If it doesn't,
you can get @code{readline} from any @code{GNU} mirror site.},
you can specify this option to obtain readline features (line editing,
history recall, etc) in the @code{opt} menu.  If you will be using the
menu even a little bit, these features are very convenient.
@item --enable-flagonezero
By default, flag values of true and false are recorded (to the @code{.opt} 
file for instance) with @samp{+} or @samp{-},
respectively; eg, @code{-v+} turns on the @code{v}-flag.  But if you
invoke @code{--enable-flagonezero}, then true and false are encoded as
@samp{1} and @samp{0} instead.  If you have a lot of long option names,
it looks a little cleaner (some might argure) to have @samp{--verbose=0}
rather than the default @samp{--verbose=-}.
@end table

@item The next step is easy, just type
@samp{make}.
If this fails, you may want to reconfigure in the previous step.

@item If you are brave, or overly cautious, you can now type 
@samp{make check}.
At this point, all this does is 
go into the @file{test/} directory and run the script
@samp{checkopt}.
The tests in this directory also serve as example code to show you
how to use the opt package in your own programs.

@item The last step is to type
@samp{make install} 
but you should be sure you have permission to write to the
directories where @file{libopt.a} and @file{opt.h} will be copied.  
This is
by default @file{/usr/local/lib} and @file{/usr/local/include}, but that
can be changed at the configure step (see @file{INSTALL} for details).
Unless you are installing @code{opt} into your personal directory,
you will probably have to become "root" before you do this
step.
@end enumerate

@node recipe, Global variables, Installation, Etc
@section Adding @code{opt} to existing code: a recipe
Suppose your code initially
looks like this:
@example
/* yourprogram.c */
#include <stdio.h>

int N=5;           /* Global variable */

int
main(int argc, char **argv)
@{
        /** do some complicated thing  **
         ** that depends on value of N **/
@}
@end example

You want to use the @code{opt} package to make the variable @var{N} into
a parameter that can be altered on the command line.  Here is the recipe.

@example
/* yourprogramonopt.c */
#include <stdio.h>
#include <opt.h>

int N=5;           /* Global variable */

int
youroldmain(int argc, char **argv)
@{
        /** do some complicated thing  **
         ** that depends on value of N **/
@}

int
main(int argc, char **argv)
@{
        optreg(&N,OPT_INT,'N',"Number that complicated thing depends on");
        optMain(youroldmain);
        opt(&argc,&argv)
        return youroldmain(argc,argv);
@}
@end example
Basically, you need to include the @file{opt.h} header file, 
register the variables that will be command line parameters, 
register your original @samp{main} function (only now renamed not to
conflict with the new @samp{main()}),
call the @samp{opt()} function itself, and then call your
original @samp{main()} function (now renamed).

If the ``complicated thing that depends on N''
depends on @var{argc,argv}, then the @var{argc,argv} that 
@samp{youroldmain()} will see will be the leftover arguments on 
the command line that come after the @samp{-N 5}, or the arguments
that come after @samp{--} on the command line.

When the users use your program in the menu mode, they can
try different values of @var{N}, eg
@example
-> N 5                 @i{;user types `N 5' in response to prompt `->'}
-> =                   @i{;user says to do the complicated thing}
5                      @i{;output of complicated thing, followed by prompt}
-> N 500 =             @i{;user tries another value, and says run with that}
2 2 5 5 5              @i{;computer responds}
-> N 12345678          @i{;user types in too large a value, computer hangs}
^C                     @i{;user hits ^C}
->                     @i{;computer responds with menu prompt, so user can}
                       @i{;try again with some other value}
@end example

@node Global variables, Single file, recipe, Etc
@section So, you don't like global variables?

One, they're not as bad as you might think.  Remember, these are not obscure
variables that will be interacting in odd ways with different components
of a complicated whole; these are the variables that you want to give the
user direct access to.  

Two, although the examples I've given (and the codes I write) 
use global variables for the user-alterable parameters, it is 
possible to use @code{opt} without global variables.  I will leave
this as an exercise for the reader who gives a damn.

@node Single file, Extensions, Global variables, Etc
@section Single file
If you want to include @code{opt} in code that you have written
to be distributed, you are by the LGPL quite welcome to do so, following
the usual caveats, provisos, and quid pro quo's.  

You may find it
inconvenient, however, to include the full distribution of opt, with
all of its automake'd Makefiles, its multiple source files, and the
extra test and extension directories.  As long as your distribution 
is not an extension to opt whose purpose is ever fancier options
parsing, but instead does something useful and just uses opt for 
its command line processing, then you are permitted to include only
the minimal source needed to make @file{libopt.a}.  In fact, to simplify this
task, you can do a @samp{make opt.c} in the @file{src/} directory and 
a single file, called @file{opt.c} of course, will be generated.  
(It is possible that the @code{opt} distribution will already have an
@file{opt.c} made for you.) You
are free to include @file{opt.c} along with @file{opt.h} in your distribution.
You don't even need to make a @file{libopt.a} if you don't want to.
Just have your @file{Makefile} include lines to this effect:
@example
        opt.o: opt.c opt.h
               $(CC) $(CFLAGS) -c opt.c

        yourprogram.o: yourprogram.c opt.h
               ...

        yourprogram: yourpgram.o ... opt.o
               $(CC) $(LDFLAGS) -o yourprogram yourprogram.o ... opt.o
@end example
Note that when you make @file{opt.c}, an LGPL style copyright will appear.
You are required to keep that copyright intact, and make sure it includes
a pointer so that users of your distribution can find my full @code{opt}
distribution, if they want it.

@node Extensions, Bugs, Single file, Etc
@section Extensions

@table @samp
@item tkopt
is a
Tk/Tcl script that is used as a front end to programs
that have an @code{opt} interface.  To use it type
@example
        tkopt program [options]
@end example
and a window will pop up which will permit you to edit all
the registered 
options and parameters, and to run the program.  The beauty of @samp{tkopt}
is that it knows nothing about the program @samp{program} beforehand.  
It learns what the options are by running @samp{program --help}
and parsing the standard usage message that is output.  It also runs
@samp{program %tmp.opt} and then reads the @file{tmp.opt} file to
determine the defaults.

@item opt.pl
is an old Perl options processing library that is no longer supported,
and no longer included with distributions of opt, but in it's place...

@item Opt.pm
is a Perl package module which can be @code{use}'d by other Perl
scripts to achieve an opt-like interface.  The main bug
are that you can already get pretty good option parsing with
only a few lines of Perl, and there exists other packages 
(eg, @code{Getopt::Long}) that perform quite powerful processing.
What @code{Opt.pm} provides is nearly identical behavior 
to the C version.  Thus, you can use @code{tkopt} as a front-end to
perl scripts using @code{Opt.pm} just like you can use it for
C programs linked with @code{libopt.a}.

@item READLINE
If you configure @code{opt} with the @samp{--with-readline} feature, then
@code{GNU readline} features (line editing, previous line retrieval,
etc) will be available in the menu mode of @code{opt}.  
To link your program to this
code, you'll need to have the @samp{readline} and @samp{termcap}
libraries available. But this is all done automagically (where by
"magic" I mean code that is embarassingly complicated) by the 
configure script.  So if @file{libopt.a} is built with this option enabled,
it will actually incorporate the @samp{readline} and @samp{termcap}
libraries within itself, and you don't need to do anything different
on the linking step.  In particular, you do NOT need to add
@samp{-lreadline -ltermcap} to the @samp{cc} command line.
If it fails, and you don't feel like trying to figure out why, just
reconfigure without the @samp{--with-readline} option.  It's nice, but 
not really crucial.
@end table

@node Bugs, Warranty, Extensions, Etc
@section Bugs

Using @code{opt} promotes the use of global variables for the parameters
that @code{opt} sets.  Global variables are generally considered harmful
to your health, but in my experience, this has rarely been a problem for
variables that you want the user to have access to anyway.

Another bug is that @code{opt} doesn't look much like the
standard and GNU's @code{getopt} package, even though it does pretty
much the same thing.  Partly this is a design
choice; I wanted something that was very easy to "attach" to the code.
In particular, with @code{opt}, you register options and associate them
with variables; this tends to be a little more compact (and in my view
more convenient) than the loop and case-statement approach used by
@code{getopt}.  Also, @code{opt} has a few more bells and whistles.  If
I were smart, I would have built @code{opt} as an add-on to the standard
@code{getopt}.

@node    Warranty, Copying, Bugs, Etc
@unnumberedsec Warranty
none.

@node   Copying,  , Warranty, Etc
@unnumberedsec Copying

   The subroutines and source code in the @code{opt} package are "free".
The precise meaning of this statement is codified in the GNU Library General
Public License, which is described in the file @file{COPYING} that should
be included in the @code{opt} distribution.  If it is not, you can
obtain a copy from the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  My own 
imprecise interpretation of that license, as it applies to @code{opt}, follows.
I should say that this is a heavily edited version of a @samp{Copying}
section that I copied from some other GNU package (now forgotten).

Everyone is free to use this software and free to redistribute
it on a free basis.  The @code{opt} library is not in the
public domain; it is copyrighted and there are restrictions on its
distribution, but these restrictions are designed to permit everything
that a good cooperating citizen would want to do.  What is not allowed
is to prevent or inhibit others from further sharing any version of this
software that they might get from you.

   Specifically, I want to make sure that you have the right to give
away copies of @code{opt}, that you receive
source code or else can get it if you want it, that you can change @code{opt}
or use pieces of it in new free programs, and that you know
you can do these things.

   To make sure that everyone has such rights, I cannot and do not
give you the "right" to
deprive anyone else of these rights.  For example, if you distribute
copies of the @code{opt}-related code, you must give the recipients all
the rights that you have.  You must make sure that they, too, receive or
can get the source code.  And you must tell them their rights.

   Also, for my own protection, I must make certain that everyone
finds out that there is no warranty for 
@code{opt}.  If this software is modified by someone else and passed
on, I want the recipients to know that what they have is not what I
distributed, so that any problems introduced by others will not reflect
on my reputation, feeble though it may be.

   Let me say that by @code{opt}-related, I mostly mean @code{opt}-derived.
If your software does something substantially different from @code{opt},
but uses @code{opt} for its command line processing, then you can do what
pretty much 
you like with that code: sell it for a profit, design weapons of mass
destruction, etc.  But you should make it clear to the users of your code
that the options parsing is done by software that is free; you should provide
the @code{opt} source code, or at least provide the users with a pointer
to where the code is available.  (Currently, that is 
@samp{http://nis-www.lanl.gov/~jt/Software} and 
@samp{ftp://nis-ftp.lanl.gov/pub/users/jt/Software/opt}.)

Happy hacking to all.

@contents
@bye