Provided by: gnuspool_1.7_i386 bug

NAME

       spsyntax - option handling for GNUspool programs

DESCRIPTION

       All of the options referred to in the descriptions of the shell-level
       programs for GNUspool below may be supplied in a configuration file
       (q.v.), or in an environment variable whose name is the same as the
       calling program, except that it is in lower case.

       This may enable defaults to be supplied according to the application
       from which the program is invoked. However any options and arguments
       supplied on the command line usually take priority.

       Additionally by editing the appropriate message file (q.v.) it is
       possible to change the option letters and keywords from those
       described.

   Option types
       In nearly all cases there are two alternative ways of supplying
       options:

       o   Via a traditional Unix-style -letter option, for example as -z.

       o   Via a keyword-style option, such as "+zero-charge". Keywords are
           case-insensitive.

   Option syntax
       The syntax of options is intended to be as flexible as possible.
       Options which do not take arguments may be grouped together as in

               -wmv

       or they may be given separately as in

               -w -m -v

       White space is optional in the case of options which do take arguments,
       thus both

               -p150

       and

               -p 150

       are acceptable and have the same effect.

       If the keyword version of an option is given, then it must be separated
       from its argument by white space thus

               +priority 150

   Configuration files
       To save the user from having to specify commonly-used combinations of
       options, there are mechanisms enabling these to be supplied to each
       program automatically.

       One mechanism is the use of a configuration file, .gnuspool in the
       current or user's home directory. The other is the use of an
       environment variable.

       These files may also be used to specify alternative message files.

       The format of configuration files is akin to a set of environment
       variable assignments, with empty lines and lines beginning with "#"
       being ignored.

       The name assigned to is the same as that of the calling program but in
       upper case and with "-" changed to "_" (underscore), for example that
       corresponding to gspl-pq is "GSPL_PQ" etc. This is the same as for the
       corresponding environment variable.

       Usually options are taken from the following places in order, so that
       later-processed ones override earlier ones:

       Standard defaults
           Each program has a set of standard defaults which are used to
           initialise the parmaters when the program is invoked.

       User profile
           In some cases, for example default priority, the user's profile as
           displayed by gspl-user(1) is used to initialise the defaults.

       Home directory
           The file ~/.gnuspool is read, and any options specified therein
           (i.e. with an assignment to the appropriate name) are interpreted.

           Please note that for historical reasons the actual path is
           ~$LIBRARY/.gnuspool. If the environment variable "LIBRARY" is null,
           then this will be equivalent to .gnuspool in the user's home
           directory.

       Environment
           Any options specified in the appropriate environment variable (you
           will almost certainly have to use quotes when setting it via the
           shell in order to preserve the white space) are read and
           interpreted.

       Current Directory
           The file .gnuspool is read, and any options specified therein (i.e.
           with an assignment to the appropriate name) are interpreted.

           Note that this may mean that the .gnuspool file is read twice if
           the command is run from the current directory. Beware therefore of
           options which are cumulative, such as arguments and redirections,
           and use the "cancel existing" options.

       Command line
           Any options specified on the command line are interpreted last.

       Most options have inverses so that it is possible to reset anything
       which may have been set by previously-read options. Extra care should
       be taken with cumulative options, notably arguments and redirections,
       so that these are not doubled, especially in the case where the home
       directory is also the current directory.

   Option path
       The above description of the order of selection of configuration files,
       environment and command-line options is the default.

       It may be desirable to change the order of selection of options, in to
       eliminate some alternative locations or to include others.

       The environment variable "GS_CONFIGPATH" may be set to a colon-
       separated list of directories (environment variables and "~"user
       constructs are appropriately interpreted).

       The symbol "!" is used to represent the relevant environment variable,
       and "-" is used to represent option arguments.

       The default value of "GS_CONFIGPATH" is

               ~$LIBRARY:!:.:-

       This provides the interpretation of options in various configuration
       files and the environment which is documented above.

       Note that it is possible to eliminate or override the interpretation of
       options on the command line by removing or relocating the "-". This may
       have very surprising effects especially where configuration files wipe
       out the effects of options which may have been set on the command line.
       Where the interpretation of options has been removed altogether, then
       any options supplied will probably be objected to or misinterpreted as
       file names or similar.

       The commands

               +freeze-home

       and

               +freeze-current

       and equivalents do not take into account the value of "GS_CONFIGPATH"
       in any way.

       Finally please note that any non-existent or inaccessible directories
       and files will (usually) be silently ignored. If a configuration file
       appears to exist but is inaccessible, a diagnostic may be given;
       however in some cases this may be misleading due to the fact that
       various versions of Unix are misleading or inconsistent with regard to
       the error codes reported from an attempt to open a non-existent or
       inaccessible file in a non-existent or inaccessible directory.

   Message files
       As well as providing help and error messages, screen key assignments
       etc, message files also provide the option letters and keyword names
       used to specify the options.

       For each command, there is a default message file. For most of the
       shell-based commands, this is sprest.help. Alternative message files
       may be specified using an environment variable or configuration file
       assigning values to a name. For most of the shell-based commands, this
       is "SPRESTCONF".

       Within the message file itself, the option letters and keywords are set
       up using sequences of the form

               A300:?,explain

       Comments and the context should make clear which commands these options
       relate to.

       These sequences define

       A state number
           The state number, in the above example 300, which is used
           internally to denote the argument.

       option letters
           A single character, often a letter, but in the above example "?",
           which is the single-character variant of the option, thus "-?".

           Several option letters, each separated by commas may be defined. To
           define <,> itself as an option "letter", use "\,".

       option keywords
           A string of alphanumerics, possibly including hyphens and
           underscores, is used to denote an option keyword, in the above
           example "+explain". Several such keywords may be defined, each
           separated by commas. Note that the case of letters in the keywords
           is discarded.

   Location of message files
       It is possible to specify alternative locations for message files so
       that alternatives are selected according to the application being run
       etc.

       The location may be specified using configuration files in a similar
       fashion to the search for options, except that the search runs the
       other way.

       The search is in the following order:

       Current Directory
           If a configuration file in the current directory specifies a
           location for the message file, by means of an assignment to the
           relevant variable (for most shell-based commands this is
           "SPRESTCONF"), then this file is taken.

           Environment variables in the form $ABC and users' home directories
           in the form "~"user are appropriately expanded. The sequence $0 is
           replaced by the name of the program being invoked. (This process
           may run recursively up to a level of 10).

       Environment
           If the relevant environment variable (for most shell-based commands
           this is "SPRESTCONF") specifies a location, then this is taken.

       Home Directory
           A configuration file in the home directory may specify a location
           for the message file.

       Default Location
           If none of the above specify a replacment message file then the
           default location is taken.

       If a file is specified but does not exist, then this is a fatal error.

       However there is an additional step to assist the user to set up some
       alternative files with a default name.

       Should the file not exist, then the search falls back to a name
       generated by taking the last part of the default file name (for example
       rest.conf) and substituting this for the last part of the file name
       specified.

       For example if the normal message file for the command were

               rest.help

       and the user had specified in a configuration file

               SPRESTCONF=~/$0.help

       then if he or she were to run, say, gspl-pr, then the file

               ~/gspl-pr.help

       would be searched for. If this did not exist, then a search would be
       made for

               ~/rest.help

   Path to locate message files
       The above search path may be modified using the environment variable
       "GS_HELPPATH". The interpretation is very similar to the description
       above for "GS_CONFIGPATH", except that "-" fields are ignored.

       The default value of "GS_HELPPATH" is ".:!:~$LIBRARY" giving the
       interpretation described above. Note that this is in the opposite order
       to "GS_CONFIGPATH".

FILES

       ~/.gnuspool configuration file (home directory)

        .gnuspool configuration file (current directory)

ENVIRONMENT

       GS_CONFIGPATH
           Path to search for options in.

       GS_HELPPATH
           Path to search for location of message files in.

COPYRIGHT

       Copyright (c) 2009 Free Software Foundation, Inc.  This is free
       software. You may redistribute copies of it under the terms of the GNU
       General Public License <http://www.gnu.org/licenses/gpl.html>.  There
       is NO WARRANTY, to the extent permitted by law.

AUTHOR

       John M Collins, Xi Software Ltd.