-@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).
-* Cairo driver class:: Configuration of Cairo 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 `cairo' 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 Cairo driver class
-@section The Cairo driver class
-
-The @code{cairo} driver class can produce output in PDF, PostScript,
-and SVG formats. It has full support for international character
-sets.
-
-The Cairo driver is only available if your copy of PSPP was built with
-the Cairo library.
-
-The available options are listed below.
-
-@table @code
-@item output-file=@var{file-name}
-
-File to which output should be sent. Default: @code{"pspp.pdf"}.
-
-@item output-type=@var{output-type}
-
-Type of output to write to the output file, one of @code{pdf},
-@code{ps}, or @code{svg}. Default: @code{pdf}.
-
-@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 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 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{font-name}
-@itemx emph-font=@var{font-name}
-@itemx fixed-font=@var{font-name}
-
-Sets the font used for proportional, emphasized, or fixed-pitch text.
-Most systems support CSS-like font names such as ``serif'' and
-``monospace'', but a wide range of system-specific font are likely to
-be supported as well.
-
-Default: proportional font @code{serif}, emphasis font @code{serif
-italic}, fixed-pitch font @code{monospace}.
-
-@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, either @samp{png} or @samp{none}.
-Default: @samp{png}.
-
-Charts are always disabled if your installation of PSPP was compiled
-without the @code{cairo} library.
-
-@item paginate=@var{boolean}
-
-If set, a formfeed will be written at the end of every page. Default:
-@code{on}.
-
-@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