Ubuntu Manpage: spsyntax - option handling for GNUspool programs

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:

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

• 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.

GNUspool Release 1                                 2009-05-18                                        SPSYNTAX(5)