-@node Configuration, Portable File Format, Concept Index, Top
+@node Configuration
@appendix Configuring PSPP
@cindex configuration
@cindex PSPP, configuring
* Miscellaneous configuring:: Even more configuration variables.
@end menu
-@node File locations, Configuration techniques, Configuration, Configuration
+@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{~/.pspp}, then the package system configuration directory (usually
+@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, Configuration files, File locations, Configuration
+@node Configuration techniques
@section Configuration techniques
There are many ways that PSPP can be configured. These are
Some of the above may not apply to a particular setting.
-@node Configuration files, Environment variables, Configuration techniques, Configuration
+@node Configuration files
@section Configuration files
Most configuration files have a common form:
Blank lines, and lines that contain only white space, are ignored.
@end itemize
-@node Environment variables, Output devices, Configuration files, Configuration
+@node Environment variables
@section Environment variables
You may think the concept of environment variables is a fairly simple
* Predefined variables:: A few variables are automatically defined.
@end menu
-@node Environment substitutions, Predefined variables, Environment variables, Environment variables
+@node Environment substitutions
@subsection Environment substitutions
Much of the power of environment variables lies in the way that they may
Undefined variables expand to a empty value.
-@node Predefined variables, , Environment substitutions, Environment variables
+@node Predefined variables
@subsection Predefined environment variables
There are two environment variables predefined for use in environment
Nothing prevents these values from being overridden, although it's a
good idea not to do so.
-@node Output devices, PostScript driver class, Environment variables, Configuration
+@node Output devices
@section Output devices
Configuring output devices is the most complicated aspect of configuring
Define a driver in terms of other drivers.
@item macro definitions
-Define environment variables local to the the output driver
+Define environment variables local to the output driver
configuration file.
@item device definitions
* Macro definitions:: Environment variables local to @file{devices}.
* Device definitions:: Output device descriptions.
* Dimensions:: Lengths, widths, sizes, @enddots{}
-* papersize:: Letter, legal, A4, envelope, @enddots{}
* Distinguishing line types:: Details on @file{devices} parsing.
* Tokenizing lines:: Dividing @file{devices} lines into tokens.
@end menu
-@node Driver categories, Macro definitions, Output devices, Output devices
+@node Driver categories
@subsection Driver categories
Drivers can be divided into categories. Drivers are specified by their
It is an error if the list is not empty when the end of @file{devices}
is reached.
-@node Macro definitions, Device definitions, Driver categories, Output devices
+@node Macro definitions
@subsection Macro definitions
Macro definitions take the form @samp{define @var{macroname}
@end table
@end itemize
-@node Device definitions, Dimensions, Macro definitions, Output devices
+@node Device definitions
@subsection Driver definitions
Driver definitions are the ultimate purpose of the @file{devices}
Options are dependent on the driver. See the driver descriptions for
details.
-@node Dimensions, papersize, Device definitions, Output devices
+@node Dimensions
@subsection Dimensions
Quite often in configuration it is necessary to specify a length or a
@end itemize
@end itemize
-@node papersize, Distinguishing line types, Dimensions, Output devices
-@subsection Paper sizes
-
-Output drivers usually deal with some sort of hardcopy media. This
-media is called @dfn{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 @file{papersize}.
-@xref{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: @samp{legal} and @samp{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 (@pxref{Dimensions}) separated
-by either @samp{x} or @samp{by}, then those are taken to be the paper
-size, in order of width followed by length. There @emph{must} be at
-least one space on each side of @samp{x} or @samp{by}.
-
-Otherwise the line must be of the form
-@samp{"@var{paper-1}"="@var{paper-2}"}. In this case the target of the
-search becomes paper name @var{paper-2} and the search through the file
-continues.
-
-@node Distinguishing line types, Tokenizing lines, papersize, Output devices
+@node Distinguishing line types
@subsection How lines are divided into types
The lines in @file{devices} are distinguished in the following manner:
Otherwise, the line is ill-formed.
@end enumerate
-@node Tokenizing lines, , Distinguishing line types, Output devices
+@node Tokenizing lines
@subsection How lines are divided into tokens
Each driver definition line is run through a simple tokenizer. This
Tokens, outside of quoted strings, are delimited by white space or equals
signs.
-@node PostScript driver class, ASCII driver class, Output devices, Configuration
+@node PostScript driver class
@section The PostScript driver class
The @code{postscript} driver class is used to produce output that is
The available options are listed below.
@table @code
-@item output-file=@var{filename}
+@item output-file=@var{file-name}
-File to which output should be sent. This can be an ordinary filename
-(i.e., @code{"pspp.ps"}), a pipe filename (i.e., @code{"|lpr"}), or
+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}
@item paper-size=@var{paper-size}
-Paper size, either as a symbolic name (i.e., @code{letter} or @code{a4})
-or specific measurements (i.e., @code{8-1/2x11} or @code{"210 x 297"}.
-@xref{papersize, , Paper sizes}. Default: @code{letter}.
+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}
Sets the width of the lines used in tables. Default: @code{0.5pt}.
@end table
-@node ASCII driver class, HTML driver class, PostScript driver class, Configuration
+@node ASCII driver class
@section The ASCII driver class
The ASCII driver class produces output that can be displayed on a
The available options are listed below.
@table @code
-@item output-file=@var{filename}
+@item output-file=@var{file-name}
-File to which output should be sent. This can be an ordinary filename
-(e.g., @code{"pspp.txt"}), a pipe filename (e.g., @code{"|lpr"}), or
+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:
@item length=@var{line-count}
-Physical length of a page, in lines. Headers and margins are subtracted
-from this value. Default: @code{66}.
+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, in characters. Margins are subtracted from
-this value. Default: @code{130}.
+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}
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},
you might pass the output.
@end table
-@node HTML driver class, Miscellaneous configuring, ASCII driver class, Configuration
+@node HTML driver class
@section The HTML driver class
The @code{html} driver class is used to produce output for viewing in
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:
+There are only a few options:
@table @code
-@item output-file=@var{filename}
+@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"}.
-File to which output should be sent. This can be an ordinary filename
-(i.e., @code{"pspp.ps"}), a pipe filename (i.e., @code{"|lpr"}), or
-stdout (@code{"-"}). Default: @code{"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,, HTML driver class, Configuration
+@node Miscellaneous configuring
@section Miscellaneous configuration
The following environment variables can be used to further configure
@file{.}
@item
-@file{~/.pspp/include}
+@file{$HOME/.pspp/include}
@item
@file{/usr/local/lib/pspp/include}
The basename used to search for the driver definition file.
@xref{Output devices}. @xref{File locations}. Default: @code{devices}.
-@item STAT_OUTPUT_PAPERSIZE_FILE
-
-The basename used to search for the papersize file. @xref{papersize}.
-@xref{File locations}. Default: @code{papersize}.
-
@item STAT_OUTPUT_INIT_PATH
-The path used to search for the driver definition file and the papersize
-file. @xref{File locations}. Default: the standard configuration path.
+The path used to search for the driver definition file.
+@xref{File locations}. Default: the standard configuration path.
@item TMPDIR