Configuring PSPP
****************

This chapter describe how to configure PSPP for your system.

Locating configuration files
============================

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

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.

 1. Syntax commands that modify settings, such as SET.  See SET.

 2. Command-line options.  See Invocation.

 3. PSPP-specific environment variable contents.  See Environment variables.

 4. General environment variable contents.  See Environment variables.

 5. Configuration file contents.  See Configuration files.

 6. Fallback defaults.

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

Configuration files
===================

Most configuration files have a common form:

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

  * Before anything else is done, trailing white space is removed.

  * When a line ends in a backslash (\), the backslash is removed, and the next line is read and appended to the current line.

       - White space preceding the backslash is retained.

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

       - It is an error if the last line in the file ends in a backslash.

  * Comments are introduced by an octothorpe (#), and continue until the end of the line.

       - An octothorpe inside balanced pairs of double quotation marks (") or single quotation marks (') does not introduce a comment.

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

       - Line splicing takes place before comment removal.

  * Blank lines, and lines that contain only white space, are ignored.

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:

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 ($) are retained without change.  Dollar signs introduce environment variable references.  References take three forms:

$VAR
     Replaced by the value of environment variable VAR.  VAR must consist of either one or more letters, or exactly one non-alphabetic character other than a left brace ({).

${VAR}
     Same as above, but VAR may contain any character (except }).

$$
     Replaced by a single dollar sign.

Undefined variables expand to a empty value.

Predefined environment variables
--------------------------------

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

VER
     Defined as the version number of PSPP, as a string, in a format something like 0.9.4.

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 i586-unknown-linux.  This is somewhat dependent on the system used to compile PSPP.

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

Output devices
==============

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

Lines in devices are divided into three categories, described briefly in the table below:

driver category definitions
     Define a driver in terms of other drivers.

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

device definitions
     Describe the configuration of an output device.

The following sections further elaborate the contents of the devices file.

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 -o DEVICE command-line option (see Invocation).

Categories are specified with a line of the form CATEGORY=DRIVER1 DRIVER2 DRIVER3 ... DRIVERN.  This line specifies that the category CATEGORY is composed of drivers named DRIVER1, 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 (see 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 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 CATEGORY.  If a matching item is found, it is deleted.  If there was a match, the list of drivers (DRIVER1 through DRIVERN) 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 devices is reached.

Macro definitions
-----------------

Macro definitions take the form define MACRONAME DEFINITION.  In such a macro definition, the environment variable MACRONAME is defined to expand to the value DEFINITION. Before the definition is made, however, any macros used in DEFINITION are expanded.

Please note the following nuances of macro usage:

  * For the purposes of this section, macro and environment variable are synonyms.

  * Macros may not take arguments.

  * Macros may not recurse.

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

  * Macros override other all environment variables of the same name (within the scope of devices).

  * Earlier macro definitions for a particular KEY override later ones.  In particular, macro definitions on the command line override those in the device definition file.  See Non-option Arguments.

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

     viewwidth
          Defined as the width of the console screen, in columns of text.

     viewlength
          Defined as the length of the console screen, in lines of text.

Driver definitions
------------------

Driver definitions are the ultimate purpose of the 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 (:).  Each line is subjected to environment variable interpolation before it is processed further (see Environment substitutions).  From left to right, the four fields are, in brief:

driver name
     A unique identifier, used to determine whether to enable the driver.

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

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

     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.

     printer

          Indicates that the device is a printer.

     listing

          Indicates that the device is a listing file.

     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.  See SET, for more information.

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

The driver is enabled if:

 1. Its driver name is specified on the command line, or

 2. It's in a category specified on the command line, or

 3. If no categories or driver names are specified on the command line, it is in category default.

For more information on driver names, see 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.

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

  * You can specify dimensions in decimal form (12.5) or as fractions, either as mixed numbers (12-1/2) or raw fractions (25/2).

  * 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:

     in
          inch (1 in = 2.54 cm)

     "
          inch (1 in = 2.54 cm)

     pt
          printer's point (1 in = 72.27 pt)

     pc
          pica (12 pt = 1 pc)

     bp
          PostScript point (1 in = 72 bp)

     cm
          centimeter

     mm
          millimeter (10 mm = 1 cm)

     dd
          didot point (1157 dd = 1238 pt)

     cc
          cicero (1 cc = 12 dd)

     sp
          scaled point (65536 sp = 1 pt)

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

       - Numbers less than 50 are assumed to be in inches.

       - Numbers 50 or greater are assumed to be in millimeters.

Paper sizes
-----------

Output drivers usually deal with some sort of hardcopy media.  This media is called paper by the drivers, though in reality it could be a transparency or film or thinly veiled sarcasm.  To make it easier for you to deal with paper, PSPP allows you to have (of course!) a configuration file that gives symbolic names, like ``letter'' or ``legal'' or ``a4'', to paper sizes, rather than forcing you to use cryptic numbers like ``8-1/2 x 11'' or ``210 by 297''.  Surprisingly enough, this configuration file is named papersize. See Configuration files.

When PSPP tries to connect a symbolic paper name to a paper size, it reads and parses each non-comment line in the file, in order.  The first field on each line must be a symbolic paper name in double quotes. Paper names may not contain double quotes.  Paper names are not case-sensitive: legal and Legal are equivalent.

If a match is found for the paper name, the rest of the line is parsed. If it is found to be a pair of dimensions (see Dimensions) separated by either x or by, then those are taken to be the paper size, in order of width followed by length.  There must be at least one space on each side of x or by.

Otherwise the line must be of the form "PAPER-1"="PAPER-2".  In this case the target of the search becomes paper name PAPER-2 and the search through the file continues.

How lines are divided into types
--------------------------------

The lines in devices are distinguished in the following manner:

 1. Leading white space is removed.

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

 3. Otherwise, the line is scanned for the first instance of a colon (:) or an equals sign (=).

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

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

 6. Otherwise, the line is ill-formed.

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 (=).  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 (' or ") and, in general, continues until the next occurrence of that same character.  The following standard C escapes can also be embedded within strings:

\'
     A single-quote (').

\"
     A double-quote (").

\?
     A question mark (?).  Included for hysterical raisins.

\\
     A backslash (\).

\a
     Audio bell (ASCII 7).

\b
     Backspace (ASCII 8).

\f
     Formfeed (ASCII 12).

\n
     New-line (ASCII 10)

\r
     Carriage return (ASCII 13).

\t
     Tab (ASCII 9).

\v
     Vertical tab (ASCII 11).

\OOO
     Each 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.

\xHH
     Each 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.

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

The PostScript driver class
===========================

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

The available options are listed below.

output-file=FILENAME

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

headers=BOOLEAN

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

paper-size=PAPER-SIZE

     Paper size, either as a symbolic name (i.e., letter or a4) or specific measurements (i.e., 8-1/2x11 or "210 x 297". See Paper sizes.  Default: letter.

orientation=ORIENTATION

     Either portrait or landscape.  Default: portrait.

left-margin=DIMENSION
right-margin=DIMENSION
top-margin=DIMENSION
bottom-margin=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 Dimensions.  Default: 0.5in.

prop-font=AFM-FILE[,FONT-FILE[,ENCODING-FILE]]
emph-font=AFM-FILE[,FONT-FILE[,ENCODING-FILE]]
fixed-font=AFM-FILE[,FONT-FILE[,ENCODING-FILE]]

     Sets the font used for proportional, emphasized, or fixed-pitch text. The only required value is AFM-FILE, the AFM file for the font.

     If specified, 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 ENCODING-FILE, if specified. Each line in 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 # are also allowed.

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

     Default: proportional font Times-Roman.afm, emphasis font Times-Italic.afm, fixed-pitch font Courier.afm.

font-size=FONT-SIZE

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

line-gutter=DIMENSION

     Sets the width of white space on either side of lines that border text or graphics objects.  See Dimensions.  Default: 1pt.

line-spacing=DIMENSION

     Sets the spacing between the lines in a double line in a table. Default: 1pt.

line-width=DIMENSION

     Sets the width of the lines used in tables.  Default: 0.5pt.

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

The available options are listed below.

output-file=FILENAME

     File to which output should be sent.  This can be an ordinary filename (e.g., "pspp.txt"), a pipe filename (e.g., "|lpr"), or stdout ("-").  Default: "pspp.list".

paginate=BOOLEAN

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

tab-width=TAB-WIDTH-VALUE

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

headers=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: on.

length=LINE-COUNT

     Physical length of a page, in lines.  Headers and margins are subtracted from this value.  Default: 66.

width=CHARACTER-COUNT

     Physical width of a page, in characters.  Margins are subtracted from this value.  Default: 130.

top-margin=TOP-MARGIN-LINES

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

bottom-margin=BOTTOM-MARGIN-LINES

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

box[LINE-TYPE]=BOX-CHARS

     The characters used for lines in tables produced by the ASCII driver can be changed using this option.  LINE-TYPE is used to indicate which type of line to change; BOX-CHARS is the character or string of characters to use for this type of line.

     LINE-TYPE must be a 4-digit number.  The digits are in the order `right', `bottom', `left', `top'.  The possibilities for each digit are:

     0
          No line.

     1
          Single line.

     2
          Double line.

     Examples:

     box[0101]="|"

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

     box[2222]="#"

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

     box[1100]="\xda"

          Sets "\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.

     Defaults:

       * box[0000]=" "

       * box[1000]="-"

          box[0010]="-"

          box[1010]="-"

       * box[0100]="|"

          box[0001]="|"

          box[0101]="|"

       * box[2000]="="

          box[0020]="="

          box[2020]="="

       * box[3000]="="

          box[0030]="="

          box[3030]="="

       * For all others, + is used unless there are double lines or special lines, in which case # is used.

emphasis=EMPHASIS-STYLE

     How to emphasize text.  Your choices are bold, underline, or 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.

The HTML driver class
=====================

The 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 is only one option:

output-file=FILENAME

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

Miscellaneous configuration
===========================

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

HOME

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

STAT_INCLUDE_PATH

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

     UNIX

            * .

            * ~/.pspp/include

            * /usr/local/lib/pspp/include

            * /usr/lib/pspp/include

            * /usr/local/share/pspp/include

            * /usr/share/pspp/include

     MS-DOS

            * .

            * C:\PSPP\INCLUDE

            * $PATH

     Other OSes
          No default path.

TERM

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

STAT_OUTPUT_INIT_FILE

     The basename used to search for the driver definition file. See Output devices.  See File locations.  Default: devices.

STAT_OUTPUT_PAPERSIZE_FILE

     The basename used to search for the papersize file.  See papersize. See File locations.  Default: papersize.

STAT_OUTPUT_INIT_PATH

     The path used to search for the driver definition file and the papersize file.  See File locations.  Default: the standard configuration path.

TMPDIR

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

TEMP

TMP

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