Rewrote the command line parser using argp.

[pspp-builds.git] / doc / configuring.texi

@node Configuration
@appendix Configuring PSPP
@cindex configuration
@cindex PSPP, configuring

This chapter describe how to configure PSPP for your system.

@menu
* File locations::              How PSPP finds config files.
* Configuration techniques::    Many different methods of configuration...
* Configuration files::         How configuration files are read.
* Environment variables::       All about environment variables.
* Output devices::              Describing your terminal(s) and printer(s).
* PostScript driver class::     Configuration of PostScript devices.
* ASCII driver class::          Configuration of character-code devices.
* HTML driver class::           Configuration for HTML output.
* Miscellaneous configuring::   Even more configuration variables.
@end menu

@node File locations
@section Locating configuration files

PSPP searches each directory in the configuration file path for most
configuration files.  The default configuration file path searches first
@file{$HOME/.pspp}, then the package system configuration directory (usually
@file{/usr/local/etc/pspp} or @file{/etc/pspp}).  The value of
environment variable @env{PSPP_CONFIG_PATH}, if defined, overrides this
default path.  Finally, @samp{-B @var{path}} or
@samp{--config-dir=@var{path}} specified on the command line has highest
priority.

@node Configuration techniques
@section Configuration techniques

There are many ways that PSPP can be configured.  These are
described in the list below.  Values given by earlier items take
precedence over those given by later items.

@enumerate
@item
Syntax commands that modify settings, such as @cmd{SET}.  @xref{SET}.

@item
Command-line options.  @xref{Invocation}.

@item
PSPP-specific environment variable contents.  @xref{Environment
variables}.

@item
General environment variable contents.  @xref{Environment variables}.

@item
Configuration file contents.  @xref{Configuration files}.

@item
Fallback defaults.
@end enumerate

Some of the above may not apply to a particular setting.

@node Configuration files
@section Configuration files

Most configuration files have a common form:

@itemize @bullet
@item
Each line forms a separate command or directive.  This means that lines
cannot be broken up, unless they are spliced together with a trailing
backslash, as described below.

@item
Before anything else is done, trailing white space is removed.

@item
When a line ends in a backslash (@samp{\}), the backslash is removed,
and the next line is read and appended to the current line.

@itemize @minus
@item
White space preceding the backslash is retained.

@item
This rule continues to be applied until the line read does not end in a
backslash.

@item
It is an error if the last line in the file ends in a backslash.
@end itemize

@item
Comments are introduced by an octothorpe (@samp{#}), and continue until the
end of the line.

@itemize @minus
@item
An octothorpe inside balanced pairs of double quotation marks (@samp{"})
or single quotation marks (@samp{'}) does not introduce a comment.

@item
The backslash character can be used inside balanced quotes of either
type to escape the following character as a literal character.  

(This is distinct from the use of a backslash as a line-splicing
character.)

@item
Line splicing takes place before comment removal.
@end itemize

@item
Blank lines, and lines that contain only white space, are ignored.
@end itemize

@node Environment variables
@section Environment variables

You may think the concept of environment variables is a fairly simple
one.  However, the author of PSPP has found a way to complicate
even something so simple.  Environment variables are further described
in the sections below:

@menu
* Environment substitutions::   How environment substitutions are made.
* Predefined variables::        A few variables are automatically defined.
@end menu

@node Environment substitutions
@subsection Environment substitutions

Much of the power of environment variables lies in the way that they may
be substituted into configuration files.  Variable substitutions are
described below.

The line is scanned from left to right.  In this scan, all characters
other than dollar signs (@samp{$}) are retained without change.  Dollar
signs introduce environment variable references.  References
take three forms:

@table @code
@item $@var{var}
Replaced by the value of environment variable @var{var}.  @var{var} must
consist of either one or more letters, or exactly one non-alphabetic
character other than a left brace (@samp{@{}).

@item $@{@var{var}@}
Same as above, but @var{var} may contain any character (except
@samp{@}}).

@item $$
Replaced by a single dollar sign.
@end table

Undefined variables expand to a empty value.

@node Predefined variables
@subsection Predefined environment variables

There are two environment variables predefined for use in environment
substitutions:

@table @samp
@item VER
Defined as the version number of PSPP, as a string, in a format
something like @samp{0.9.4}.

@item ARCH
Defined as the host architecture of PSPP, as a string, in standard
cpu-manufacturer-OS format.  For instance, Debian GNU/Linux 1.1 on an
Intel machine defines this as @samp{i586-unknown-linux}.  This is
somewhat dependent on the system used to compile PSPP.
@end table

Nothing prevents these values from being overridden, although it's a
good idea not to do so.

@node Output devices
@section Output devices

Configuring output devices is the most complicated aspect of configuring
PSPP.  The output device configuration file is named
@file{devices}.  It is searched for using the usual algorithm for
finding configuration files (@pxref{File locations}).  Each line in the
file is read in the usual manner for configuration files
(@pxref{Configuration files}).

Lines in @file{devices} are divided into three categories, described
briefly in the table below:

@table @i
@item driver category definitions
Define a driver in terms of other drivers.

@item macro definitions
Define environment variables local to the output driver
configuration file.

@item device definitions
Describe the configuration of an output device.
@end table

The following sections further elaborate the contents of the
@file{devices} file.

@menu
* Driver categories::           How to organize the driver namespace.
* Macro definitions::           Environment variables local to @file{devices}.
* Device definitions::          Output device descriptions.
* Dimensions::                  Lengths, widths, sizes, @enddots{}
* Distinguishing line types::   Details on @file{devices} parsing.
* Tokenizing lines::            Dividing @file{devices} lines into tokens.
@end menu

@node Driver categories
@subsection Driver categories

Drivers can be divided into categories.  Drivers are specified by their
names, or by the names of the categories that they are contained in.
Only certain drivers are enabled each time PSPP is run; by
default, these are the drivers in the category `default'.  To enable a
different set of drivers, use the @samp{-o @var{device}} command-line
option (@pxref{Invocation}).

Categories are specified with a line of the form
@samp{@var{category}=@var{driver1} @var{driver2} @var{driver3} @var{@dots{}}
@var{driver@var{n}}}.  This line specifies that the category
@var{category} is composed of drivers named @var{driver1},
@var{driver2}, and so on.  There may be any number of drivers in the
category, from zero on up.

Categories may also be specified on the command line
(@pxref{Invocation}).

This is all you need to know about categories.  If you're still curious,
read on.

First of all, the term `categories' is a bit of a misnomer.  In fact,
the internal representation is nothing like the hierarchy that the term
seems to imply: a linear list is used to keep track of the enabled
drivers.

When PSPP first begins reading @file{devices}, this list contains
the name of any drivers or categories specified on the command line, or
the single item `default' if none were specified.

Each time a category definition is specified, the list is searched for
an item with the value of @var{category}.  If a matching item is found,
it is deleted.  If there was a match, the list of drivers (@var{driver1}
through @var{driver@var{n}}) is then appended to the list.

Each time a driver definition line is encountered, the list is searched.
If the list contains an item with that driver's name, the driver is
enabled and the item is deleted from the list.  Otherwise, the driver
is not enabled.

It is an error if the list is not empty when the end of @file{devices}
is reached.

@node Macro definitions
@subsection Macro definitions

Macro definitions take the form @samp{define @var{macroname}
@var{definition}}.  In such a macro definition, the environment variable
@var{macroname} is defined to expand to the value @var{definition}.
Before the definition is made, however, any macros used in
@var{definition} are expanded.

Please note the following nuances of macro usage:

@itemize @bullet
@item
For the purposes of this section, @dfn{macro} and @dfn{environment
variable} are synonyms.

@item
Macros may not take arguments.

@item
Macros may not recurse.

@item
Macros are just environment variable definitions like other environment
variable definitions, with the exception that they are limited in scope
to the @file{devices} configuration file.

@item
Macros override other all environment variables of the same name (within
the scope of @file{devices}).

@item
Earlier macro definitions for a particular @var{key} override later
ones.  In particular, macro definitions on the command line override
those in the device definition file.  @xref{Non-option Arguments}.

@item
There are two predefined macros, whose values are determined at runtime:

@table @samp
@item viewwidth
Defined as the width of the console screen, in columns of text.

@item viewlength
Defined as the length of the console screen, in lines of text.
@end table
@end itemize

@node Device definitions
@subsection Driver definitions

Driver definitions are the ultimate purpose of the @file{devices}
configuration file.  These are where the real action is.  Driver
definitions tell PSPP where it should send its output.

Each driver definition line is divided into four fields.  These fields
are delimited by colons (@samp{:}).  Each line is subjected to
environment variable interpolation before it is processed further
(@pxref{Environment substitutions}).  From left to right, the four
fields are, in brief:

@table @i
@item driver name
A unique identifier, used to determine whether to enable the driver.

@item class name
One of the predefined driver classes supported by PSPP.  The
currently supported driver classes include `postscript' and `ascii'.

@item device type(s)
Zero or more of the following keywords, delimited by spaces:

@table @code
@item screen

Indicates that the device is a screen display.  This may reduce the
amount of buffering done by the driver, to make interactive use more
convenient.

@item printer

Indicates that the device is a printer.

@item listing

Indicates that the device is a listing file.
@end table

These options are just hints to PSPP and do not cause the output to be
directed to the screen, or to the printer, or to a listing file---those
must be set elsewhere in the options.  They are used primarily to decide
which devices should be enabled at any given time.  @xref{SET}, for more
information.

@item options
An optional set of options to pass to the driver itself.  The exact
format for the options varies among drivers.
@end table

The driver is enabled if:

@enumerate
@item
Its driver name is specified on the command line, or

@item
It's in a category specified on the command line, or

@item
If no categories or driver names are specified on the command line, it
is in category @code{default}.
@end enumerate

For more information on driver names, see @ref{Driver categories}.

The class name must be one of those supported by PSPP.  The
classes supported depend on the options with which PSPP was
compiled.  See later sections in this chapter for descriptions of the
available driver classes.

Options are dependent on the driver.  See the driver descriptions for
details.

@node Dimensions
@subsection Dimensions

Quite often in configuration it is necessary to specify a length or a
size.  PSPP uses a common syntax for all such, calling them
collectively by the name @dfn{dimensions}.

@itemize @bullet
@item
You can specify dimensions in decimal form (@samp{12.5}) or as
fractions, either as mixed numbers (@samp{12-1/2}) or raw fractions
(@samp{25/2}).

@item 
A number of different units are available.  These are suffixed to the
numeric part of the dimension.  There must be no spaces between the
number and the unit.  The available units are identical to those offered
by the popular typesetting system @TeX{}:

@table @code
@item in
inch (1 @code{in} = 2.54 @code{cm})

@item "
inch (1 @code{in} = 2.54 @code{cm})

@item pt
printer's point (1 @code{in} = 72.27 @code{pt})

@item pc
pica (12 @code{pt} = 1 @code{pc})

@item bp
PostScript point (1 @code{in} = 72 @code{bp})

@item cm
centimeter

@item mm
millimeter (10 @code{mm} = 1 @code{cm})

@item dd
didot point (1157 @code{dd} = 1238 @code{pt})

@item cc
cicero (1 @code{cc} = 12 @code{dd})

@item sp
scaled point (65536 @code{sp} = 1 @code{pt})
@end table

@item
If no explicit unit is given, PSPP attempts to guess the best unit:

@itemize @minus
@item
Numbers less than 50 are assumed to be in inches.

@item
Numbers 50 or greater are assumed to be in millimeters.
@end itemize
@end itemize

@node Distinguishing line types
@subsection How lines are divided into types

The lines in @file{devices} are distinguished in the following manner:

@enumerate
@item
Leading white space is removed.

@item
If the resulting line begins with the exact string @code{define},
followed by one or more white space characters, the line is processed as
a macro definition.

@item
Otherwise, the line is scanned for the first instance of a colon
(@samp{:}) or an equals sign (@samp{=}).

@item
If a colon is encountered first, the line is processed as a driver
definition.

@item
Otherwise, if an equals sign is encountered, the line is processed as a
macro definition.

@item
Otherwise, the line is ill-formed.
@end enumerate

@node Tokenizing lines
@subsection How lines are divided into tokens

Each driver definition line is run through a simple tokenizer.  This
tokenizer recognizes two basic types of tokens.

The first type is an equals sign (@samp{=}).  Equals signs are both
delimiters between tokens and tokens in themselves.

The second type is an identifier or string token.  Identifiers and
strings are equivalent after tokenization, though they are written
differently.  An identifier is any string of characters other than
white space or equals sign.

A string is introduced by a single- or double-quote character (@samp{'}
or @samp{"}) and, in general, continues until the next occurrence of
that same character.  The following standard C escapes can also be
embedded within strings:

@table @code
@item \'
A single-quote (@samp{'}).

@item \"
A double-quote (@samp{"}).

@item \?
A question mark (@samp{?}).  Included for hysterical raisins.

@item \\
A backslash (@samp{\}).

@item \a
Audio bell (ASCII 7).

@item \b
Backspace (ASCII 8).

@item \f
Formfeed (ASCII 12).

@item \n
New-line (ASCII 10)

@item \r
Carriage return (ASCII 13).

@item \t
Tab (ASCII 9).

@item \v
Vertical tab (ASCII 11).

@item \@var{o}@var{o}@var{o}
Each @samp{o} must be an octal digit.  The character is the one having
the octal value specified.  Any number of octal digits is read and
interpreted; only the lower 8 bits are used.

@item \x@var{h}@var{h}
Each @samp{h} must be a hex digit.  The character is the one having the
hexadecimal value specified.  Any number of hex digits is read and
interpreted; only the lower 8 bits are used.
@end table

Tokens, outside of quoted strings, are delimited by white space or equals
signs.

@node PostScript driver class
@section The PostScript driver class

The @code{postscript} driver class is used to produce output that is
acceptable to PostScript printers and other interpreters.

The available options are listed below.

@table @code
@item output-file=@var{file-name}

File to which output should be sent.  This can be an ordinary file name
(i.e., @code{"pspp.ps"}), a pipe (i.e., @code{"|lpr"}), or
stdout (@code{"-"}).  Default: @code{"pspp.ps"}.

@item headers=@var{boolean}

Controls whether the standard headers showing the time and date and
title and subtitle are printed at the top of each page.  Default:
@code{on}.

@item paper-size=@var{paper-size}

Paper size.  You may specify a name (e.g.@: @code{a4}, @code{letter})
or measurements (e.g.@: @code{210x297}, @code{8.5x11in}).

The default paper size is taken from the @env{PAPERSIZE} environment
variable or the file indicated by the @env{PAPERCONF} environment
variable, if either variable is set.  If not, and your system supports
the @code{LC_PAPER} locale category, then the default paper size is
taken from the locale.  Otherwise, if @file{/etc/papersize} exists,
the default paper size is read from it.  As a last resort, A4 paper is
assumed.

@item orientation=@var{orientation}

Either @code{portrait} or @code{landscape}.  Default: @code{portrait}.

@item left-margin=@var{dimension}
@itemx right-margin=@var{dimension}
@itemx top-margin=@var{dimension}
@itemx bottom-margin=@var{dimension}

Sets the margins around the page.  The headers, if enabled, are not
included in the margins; they are in addition to the margins.  For a
description of dimensions, see @ref{Dimensions}.  Default: @code{0.5in}.

@item prop-font=@var{afm-file}[,@var{font-file}[,@var{encoding-file}]]
@itemx emph-font=@var{afm-file}[,@var{font-file}[,@var{encoding-file}]]
@itemx fixed-font=@var{afm-file}[,@var{font-file}[,@var{encoding-file}]]

Sets the font used for proportional, emphasized, or fixed-pitch text.
The only required value is @var{afm-file}, the AFM file for the font.

If specified, @var{font-file} will be downloaded to the printer at the
beginning of the print job.  The font file may be in PFA or PFB format.

The font is reencoded as specified in @var{encoding-file}, if specified.
Each line in @var{encoding-file} should consist of a PostScript
character name and a decimal encoding value (between 0 and 255),
separated by white space.  Blank lines and comments introduced by
@samp{#} are also allowed.

The files specified on these options are located as follows.  If
the file name begins with @samp{/}, then it is taken as an absolute
path.  Otherwise, PSPP searches its configuration path for the specified
name prefixed by @code{psfonts/} (@pxref{File locations}).

Default: proportional font @code{Times-Roman.afm}, emphasis font
@code{Times-Italic.afm}, fixed-pitch font @code{Courier.afm}.

@item font-size=@var{font-size}

Sets the size of the default fonts, in thousandths of a point.  Default:
10000 (10 point).

@item line-gutter=@var{dimension}

Sets the width of white space on either side of lines that border text
or graphics objects.  @xref{Dimensions}.  Default: @code{1pt}.

@item line-spacing=@var{dimension}

Sets the spacing between the lines in a double line in a table.
Default: @code{1pt}.

@item line-width=@var{dimension}

Sets the width of the lines used in tables.  Default: @code{0.5pt}.
@end table

@node ASCII driver class
@section The ASCII driver class

The ASCII driver class produces output that can be displayed on a
terminal or output to printers.  The ASCII driver has class name
@samp{ascii}.

The available options are listed below.

@table @code
@item output-file=@var{file-name}

File to which output should be sent.  This can be an ordinary file name
(e.g., @code{"pspp.txt"}), a pipe (e.g., @code{"|more"}), or
stdout (@code{"-"}).  Default: @code{"pspp.list"}.

@item chart-files=@var{file-name-template}
Template for the file names used for charts.  The name should contain
a single @samp{#}, which is replaced by the chart number.  Default:
@file{"pspp-#.png"}.

@item chart-type=@var{type}.
Type of charts to output.  Available types typically include @samp{X},
@samp{png}, @samp{gif}, @samp{svg}, @samp{ps}, @samp{cgm}, @samp{fig},
@samp{pcl}, @samp{hpgl}, @samp{regis}, @samp{tek}, and @samp{meta}.
Default: @samp{png}.

You may specify @samp{none} to disable chart output.  Charts are also
disabled if your installation of PSPP was compiled without
@code{libplot}.

@item paginate=@var{boolean}

If set, a formfeed will be written at the end of every page.  Default:
@code{on}.

@item tab-width=@var{tab-width-value}

The distance between tab stops for this device.  If set to 0, tabs will
not be used in the output.  Default: @code{8}.

@item headers=@var{boolean}

If enabled, two lines of header information giving title and subtitle,
page number, date and time, and PSPP version are printed at the top of
every page.  These two lines are in addition to any top margin
requested.  Default: @code{on}.

@item length=@var{line-count}

Physical length of a page.  Headers and margins are subtracted from
this value.  You may specify the number of lines as a number, or for
screen output you may specify @code{auto} to track the height of the
terminal as it changes.  Default: @code{66}.

@item width=@var{character-count}

Physical width of a page.  Margins are subtracted from this value.
You may specify the width as a number of characters, or for screen
output you may specify @code{auto} to track the width of the terminal
as it changes.  Default: @code{79}.

@item top-margin=@var{top-margin-lines}

Length of the top margin, in lines.  PSPP subtracts this value from
the page length.  Default: @code{2}.

@item bottom-margin=@var{bottom-margin-lines}

Length of the bottom margin, in lines.  PSPP subtracts this value from
the page length.  Default: @code{2}.

@item box[@var{line-type}]=@var{box-chars}

The characters used for lines in tables produced by the ASCII driver can
be changed using this option.  @var{line-type} is used to indicate which
type of line to change; @var{box-chars} is the character or string of
characters to use for this type of line.

@var{line-type} must be a 4-digit number.  The digits are in the order
`right', `bottom', `left', `top'.  The possibilities for each digit are:

@table @asis
@item 0
No line.

@item 1
Single line.

@item 2
Double line.
@end table

Examples:

@table @code
@item box[0101]="|"

Sets @samp{|} as the character to use for a single-width line with
bottom and top components.

@item box[2222]="#"

Sets @samp{#} as the character to use for the intersection of four
double-width lines, one each from the top, bottom, left and right.

@item box[1100]="\xda"

Sets @samp{"\xda"}, which under MS-DOS is a box character suitable for
the top-left corner of a box, as the character for the intersection of
two single-width lines, one each from the right and bottom.

@end table

Defaults:

@itemize @bullet
@item
@code{box[0000]=" "}

@item
@code{box[1000]="-"}
@*@code{box[0010]="-"}
@*@code{box[1010]="-"}

@item
@code{box[0100]="|"}
@*@code{box[0001]="|"}
@*@code{box[0101]="|"}

@item
@code{box[2000]="="}
@*@code{box[0020]="="}
@*@code{box[2020]="="}

@item
@code{box[3000]="="}
@*@code{box[0030]="="}
@*@code{box[3030]="="}

@item
For all others, @samp{+} is used unless there are double lines or
special lines, in which case @samp{#} is used.
@end itemize

@item init=@var{init-string}
If set, this string is written at the beginning of each output file.
It can be used to initialize device features, e.g.@: to enable VT100
line-drawing characters.

@item emphasis=@var{emphasis-style}

How to emphasize text.  Your choices are @code{bold}, @code{underline},
or @code{none}.  Bold and underline emphasis are achieved with
overstriking, which may not be supported by all the software to which
you might pass the output.
@end table

@node HTML driver class
@section The HTML driver class

The @code{html} driver class is used to produce output for viewing in
tables-capable web browsers such as Emacs' w3-mode.  Its configuration
is very simple.  Currently, the output has a very plain format.  In the
future, further work may be done on improving the output appearance.

There are only a few options:

@table @code
@item output-file=@var{file-name}

File to which output should be sent.  This can be an ordinary file name
(i.e., @code{"pspp.ps"}), a pipe (i.e., @code{"|lpr"}), or
stdout (@code{"-"}).  Default: @file{"pspp.html"}.

@item chart-files=@var{file-name-template}
Template for the file names used for charts, which are output in PNG
format.  The name should contain a single @samp{#}, which is replaced by
the chart number.  Default: @file{"pspp-#.png"}.
@end table

@node Miscellaneous configuring
@section Miscellaneous configuration

The following environment variables can be used to further configure
PSPP:

@table @code
@item HOME

Used to determine the user's home directory.  No default value.

@item STAT_INCLUDE_PATH

Path used to find include files in PSPP syntax files.  Defaults vary
across operating systems:

@table @asis
@item UNIX

@itemize @bullet
@item
@file{.}

@item
@file{$HOME/.pspp/include}

@item
@file{/usr/local/lib/pspp/include}

@item
@file{/usr/lib/pspp/include}

@item
@file{/usr/local/share/pspp/include}

@item
@file{/usr/share/pspp/include}
@end itemize

@item MS-DOS

@itemize @bullet
@item
@file{.}

@item
@file{C:\PSPP\INCLUDE}

@item
@file{$PATH}
@end itemize

@item Other OSes
No default path.
@end table

@item TERM

The terminal type @code{termcap} or @code{ncurses} will use, if such
support was compiled into PSPP.

@item STAT_OUTPUT_INIT_FILE

The basename used to search for the driver definition file.
@xref{Output devices}.  @xref{File locations}.  Default: @code{devices}.

@item STAT_OUTPUT_INIT_PATH

The path used to search for the driver definition file.
@xref{File locations}.  Default: the standard configuration path.

@item TMPDIR

The directory in which PSPP stores its temporary files (used when sorting 
cases or concatenating large numbers of cases).
Default: (UNIX) @file{/tmp}, (MS-DOS) @file{\}, (other OSes) empty string.

@item TEMP
@item TMP

Under MS-DOS only, these variables are consulted after TMPDIR, in this
order.
@end table