-@node Configuration, Portable File Format, Concept Index, Top
+@node Configuration
@appendix Configuring PSPP
@cindex configuration
@cindex PSPP, configuring
* 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.
+* Cairo driver class:: Configuration of Cairo devices.
* ASCII driver class:: Configuration of character-code devices.
* HTML driver class:: Configuration for HTML output.
+* PostScript driver class:: Configuration of PostScript devices.
* 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
@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
* 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}
@item class name
One of the predefined driver classes supported by PSPP. The
-currently supported driver classes include `postscript' and `ascii'.
+currently supported driver classes include `cairo' and `ascii'.
@item device type(s)
Zero or more of the following keywords, delimited by spaces:
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
-@section The PostScript driver class
+@node Cairo driver class
+@section The Cairo driver class
-The @code{postscript} driver class is used to produce output that is
-acceptable to PostScript printers and other interpreters.
+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. 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"}.
+File to which output should be sent. Default: @code{"pspp.pdf"}.
-@item headers=@var{boolean}
+@item output-type=@var{output-type}
-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}.
+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, 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}
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}
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}]]
+@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.
-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.
+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.
-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}.
+Default: proportional font @code{serif}, emphasis font @code{serif
+italic}, fixed-pitch font @code{monospace}.
@item font-size=@var{font-size}
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
@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{"|lpr"}), or
+(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:
@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
the chart number. Default: @file{"pspp-#.png"}.
@end table
-@node Miscellaneous configuring,, HTML driver class, Configuration
+@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 PostScript driver class does not support charts.
+
+The PostScript driver class is deprecated. It is likely to be removed
+in a future version of PSPP. We suggest that you use the Cairo driver
+class instead, which can output PostScript as well and has better font
+support, including support for international character sets, and does
+support charts.
+
+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 Miscellaneous configuring
@section Miscellaneous configuration
The following environment variables can be used to further configure
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
projects / pspp-builds.git / blobdiff