2 @appendix Configuring PSPP
4 @cindex PSPP, configuring
6 This chapter describe how to configure PSPP for your system.
9 * File locations:: How PSPP finds config files.
10 * Configuration techniques:: Many different methods of configuration...
11 * Configuration files:: How configuration files are read.
12 * Environment variables:: All about environment variables.
13 * Output devices:: Describing your terminal(s) and printer(s).
14 * PostScript driver class:: Configuration of PostScript devices.
15 * ASCII driver class:: Configuration of character-code devices.
16 * HTML driver class:: Configuration for HTML output.
17 * Miscellaneous configuring:: Even more configuration variables.
21 @section Locating configuration files
23 PSPP searches each directory in the configuration file path for most
24 configuration files. The default configuration file path searches first
25 @file{$HOME/.pspp}, then the package system configuration directory (usually
26 @file{/usr/local/etc/pspp} or @file{/etc/pspp}). The value of
27 environment variable @env{PSPP_CONFIG_PATH}, if defined, overrides this
28 default path. Finally, @samp{-B @var{path}} or
29 @samp{--config-dir=@var{path}} specified on the command line has highest
32 @node Configuration techniques
33 @section Configuration techniques
35 There are many ways that PSPP can be configured. These are
36 described in the list below. Values given by earlier items take
37 precedence over those given by later items.
41 Syntax commands that modify settings, such as @cmd{SET}. @xref{SET}.
44 Command-line options. @xref{Invocation}.
47 PSPP-specific environment variable contents. @xref{Environment
51 General environment variable contents. @xref{Environment variables}.
54 Configuration file contents. @xref{Configuration files}.
60 Some of the above may not apply to a particular setting.
62 @node Configuration files
63 @section Configuration files
65 Most configuration files have a common form:
69 Each line forms a separate command or directive. This means that lines
70 cannot be broken up, unless they are spliced together with a trailing
71 backslash, as described below.
74 Before anything else is done, trailing white space is removed.
77 When a line ends in a backslash (@samp{\}), the backslash is removed,
78 and the next line is read and appended to the current line.
82 White space preceding the backslash is retained.
85 This rule continues to be applied until the line read does not end in a
89 It is an error if the last line in the file ends in a backslash.
93 Comments are introduced by an octothorpe (@samp{#}), and continue until the
98 An octothorpe inside balanced pairs of double quotation marks (@samp{"})
99 or single quotation marks (@samp{'}) does not introduce a comment.
102 The backslash character can be used inside balanced quotes of either
103 type to escape the following character as a literal character.
105 (This is distinct from the use of a backslash as a line-splicing
109 Line splicing takes place before comment removal.
113 Blank lines, and lines that contain only white space, are ignored.
116 @node Environment variables
117 @section Environment variables
119 You may think the concept of environment variables is a fairly simple
120 one. However, the author of PSPP has found a way to complicate
121 even something so simple. Environment variables are further described
122 in the sections below:
125 * Environment substitutions:: How environment substitutions are made.
126 * Predefined variables:: A few variables are automatically defined.
129 @node Environment substitutions
130 @subsection Environment substitutions
132 Much of the power of environment variables lies in the way that they may
133 be substituted into configuration files. Variable substitutions are
136 The line is scanned from left to right. In this scan, all characters
137 other than dollar signs (@samp{$}) are retained without change. Dollar
138 signs introduce environment variable references. References
143 Replaced by the value of environment variable @var{var}. @var{var} must
144 consist of either one or more letters, or exactly one non-alphabetic
145 character other than a left brace (@samp{@{}).
148 Same as above, but @var{var} may contain any character (except
152 Replaced by a single dollar sign.
155 Undefined variables expand to a empty value.
157 @node Predefined variables
158 @subsection Predefined environment variables
160 There are two environment variables predefined for use in environment
165 Defined as the version number of PSPP, as a string, in a format
166 something like @samp{0.9.4}.
169 Defined as the host architecture of PSPP, as a string, in standard
170 cpu-manufacturer-OS format. For instance, Debian GNU/Linux 1.1 on an
171 Intel machine defines this as @samp{i586-unknown-linux}. This is
172 somewhat dependent on the system used to compile PSPP.
175 Nothing prevents these values from being overridden, although it's a
176 good idea not to do so.
179 @section Output devices
181 Configuring output devices is the most complicated aspect of configuring
182 PSPP. The output device configuration file is named
183 @file{devices}. It is searched for using the usual algorithm for
184 finding configuration files (@pxref{File locations}). Each line in the
185 file is read in the usual manner for configuration files
186 (@pxref{Configuration files}).
188 Lines in @file{devices} are divided into three categories, described
189 briefly in the table below:
192 @item driver category definitions
193 Define a driver in terms of other drivers.
195 @item macro definitions
196 Define environment variables local to the output driver
199 @item device definitions
200 Describe the configuration of an output device.
203 The following sections further elaborate the contents of the
207 * Driver categories:: How to organize the driver namespace.
208 * Macro definitions:: Environment variables local to @file{devices}.
209 * Device definitions:: Output device descriptions.
210 * Dimensions:: Lengths, widths, sizes, @enddots{}
211 * Distinguishing line types:: Details on @file{devices} parsing.
212 * Tokenizing lines:: Dividing @file{devices} lines into tokens.
215 @node Driver categories
216 @subsection Driver categories
218 Drivers can be divided into categories. Drivers are specified by their
219 names, or by the names of the categories that they are contained in.
220 Only certain drivers are enabled each time PSPP is run; by
221 default, these are the drivers in the category `default'. To enable a
222 different set of drivers, use the @samp{-o @var{device}} command-line
223 option (@pxref{Invocation}).
225 Categories are specified with a line of the form
226 @samp{@var{category}=@var{driver1} @var{driver2} @var{driver3} @var{@dots{}}
227 @var{driver@var{n}}}. This line specifies that the category
228 @var{category} is composed of drivers named @var{driver1},
229 @var{driver2}, and so on. There may be any number of drivers in the
230 category, from zero on up.
232 Categories may also be specified on the command line
233 (@pxref{Invocation}).
235 This is all you need to know about categories. If you're still curious,
238 First of all, the term `categories' is a bit of a misnomer. In fact,
239 the internal representation is nothing like the hierarchy that the term
240 seems to imply: a linear list is used to keep track of the enabled
243 When PSPP first begins reading @file{devices}, this list contains
244 the name of any drivers or categories specified on the command line, or
245 the single item `default' if none were specified.
247 Each time a category definition is specified, the list is searched for
248 an item with the value of @var{category}. If a matching item is found,
249 it is deleted. If there was a match, the list of drivers (@var{driver1}
250 through @var{driver@var{n}}) is then appended to the list.
252 Each time a driver definition line is encountered, the list is searched.
253 If the list contains an item with that driver's name, the driver is
254 enabled and the item is deleted from the list. Otherwise, the driver
257 It is an error if the list is not empty when the end of @file{devices}
260 @node Macro definitions
261 @subsection Macro definitions
263 Macro definitions take the form @samp{define @var{macroname}
264 @var{definition}}. In such a macro definition, the environment variable
265 @var{macroname} is defined to expand to the value @var{definition}.
266 Before the definition is made, however, any macros used in
267 @var{definition} are expanded.
269 Please note the following nuances of macro usage:
273 For the purposes of this section, @dfn{macro} and @dfn{environment
274 variable} are synonyms.
277 Macros may not take arguments.
280 Macros may not recurse.
283 Macros are just environment variable definitions like other environment
284 variable definitions, with the exception that they are limited in scope
285 to the @file{devices} configuration file.
288 Macros override other all environment variables of the same name (within
289 the scope of @file{devices}).
292 Earlier macro definitions for a particular @var{key} override later
293 ones. In particular, macro definitions on the command line override
294 those in the device definition file. @xref{Non-option Arguments}.
297 There are two predefined macros, whose values are determined at runtime:
301 Defined as the width of the console screen, in columns of text.
304 Defined as the length of the console screen, in lines of text.
308 @node Device definitions
309 @subsection Driver definitions
311 Driver definitions are the ultimate purpose of the @file{devices}
312 configuration file. These are where the real action is. Driver
313 definitions tell PSPP where it should send its output.
315 Each driver definition line is divided into four fields. These fields
316 are delimited by colons (@samp{:}). Each line is subjected to
317 environment variable interpolation before it is processed further
318 (@pxref{Environment substitutions}). From left to right, the four
319 fields are, in brief:
323 A unique identifier, used to determine whether to enable the driver.
326 One of the predefined driver classes supported by PSPP. The
327 currently supported driver classes include `postscript' and `ascii'.
330 Zero or more of the following keywords, delimited by spaces:
335 Indicates that the device is a screen display. This may reduce the
336 amount of buffering done by the driver, to make interactive use more
341 Indicates that the device is a printer.
345 Indicates that the device is a listing file.
348 These options are just hints to PSPP and do not cause the output to be
349 directed to the screen, or to the printer, or to a listing file---those
350 must be set elsewhere in the options. They are used primarily to decide
351 which devices should be enabled at any given time. @xref{SET}, for more
355 An optional set of options to pass to the driver itself. The exact
356 format for the options varies among drivers.
359 The driver is enabled if:
363 Its driver name is specified on the command line, or
366 It's in a category specified on the command line, or
369 If no categories or driver names are specified on the command line, it
370 is in category @code{default}.
373 For more information on driver names, see @ref{Driver categories}.
375 The class name must be one of those supported by PSPP. The
376 classes supported depend on the options with which PSPP was
377 compiled. See later sections in this chapter for descriptions of the
378 available driver classes.
380 Options are dependent on the driver. See the driver descriptions for
384 @subsection Dimensions
386 Quite often in configuration it is necessary to specify a length or a
387 size. PSPP uses a common syntax for all such, calling them
388 collectively by the name @dfn{dimensions}.
392 You can specify dimensions in decimal form (@samp{12.5}) or as
393 fractions, either as mixed numbers (@samp{12-1/2}) or raw fractions
397 A number of different units are available. These are suffixed to the
398 numeric part of the dimension. There must be no spaces between the
399 number and the unit. The available units are identical to those offered
400 by the popular typesetting system @TeX{}:
404 inch (1 @code{in} = 2.54 @code{cm})
407 inch (1 @code{in} = 2.54 @code{cm})
410 printer's point (1 @code{in} = 72.27 @code{pt})
413 pica (12 @code{pt} = 1 @code{pc})
416 PostScript point (1 @code{in} = 72 @code{bp})
422 millimeter (10 @code{mm} = 1 @code{cm})
425 didot point (1157 @code{dd} = 1238 @code{pt})
428 cicero (1 @code{cc} = 12 @code{dd})
431 scaled point (65536 @code{sp} = 1 @code{pt})
435 If no explicit unit is given, PSPP attempts to guess the best unit:
439 Numbers less than 50 are assumed to be in inches.
442 Numbers 50 or greater are assumed to be in millimeters.
446 @node Distinguishing line types
447 @subsection How lines are divided into types
449 The lines in @file{devices} are distinguished in the following manner:
453 Leading white space is removed.
456 If the resulting line begins with the exact string @code{define},
457 followed by one or more white space characters, the line is processed as
461 Otherwise, the line is scanned for the first instance of a colon
462 (@samp{:}) or an equals sign (@samp{=}).
465 If a colon is encountered first, the line is processed as a driver
469 Otherwise, if an equals sign is encountered, the line is processed as a
473 Otherwise, the line is ill-formed.
476 @node Tokenizing lines
477 @subsection How lines are divided into tokens
479 Each driver definition line is run through a simple tokenizer. This
480 tokenizer recognizes two basic types of tokens.
482 The first type is an equals sign (@samp{=}). Equals signs are both
483 delimiters between tokens and tokens in themselves.
485 The second type is an identifier or string token. Identifiers and
486 strings are equivalent after tokenization, though they are written
487 differently. An identifier is any string of characters other than
488 white space or equals sign.
490 A string is introduced by a single- or double-quote character (@samp{'}
491 or @samp{"}) and, in general, continues until the next occurrence of
492 that same character. The following standard C escapes can also be
493 embedded within strings:
497 A single-quote (@samp{'}).
500 A double-quote (@samp{"}).
503 A question mark (@samp{?}). Included for hysterical raisins.
506 A backslash (@samp{\}).
509 Audio bell (ASCII 7).
521 Carriage return (ASCII 13).
527 Vertical tab (ASCII 11).
529 @item \@var{o}@var{o}@var{o}
530 Each @samp{o} must be an octal digit. The character is the one having
531 the octal value specified. Any number of octal digits is read and
532 interpreted; only the lower 8 bits are used.
534 @item \x@var{h}@var{h}
535 Each @samp{h} must be a hex digit. The character is the one having the
536 hexadecimal value specified. Any number of hex digits is read and
537 interpreted; only the lower 8 bits are used.
540 Tokens, outside of quoted strings, are delimited by white space or equals
543 @node PostScript driver class
544 @section The PostScript driver class
546 The @code{postscript} driver class is used to produce output that is
547 acceptable to PostScript printers and other interpreters.
549 The available options are listed below.
552 @item output-file=@var{file-name}
554 File to which output should be sent. This can be an ordinary file name
555 (i.e., @code{"pspp.ps"}), a pipe (i.e., @code{"|lpr"}), or
556 stdout (@code{"-"}). Default: @code{"pspp.ps"}.
558 @item headers=@var{boolean}
560 Controls whether the standard headers showing the time and date and
561 title and subtitle are printed at the top of each page. Default:
564 @item paper-size=@var{paper-size}
566 Paper size. You may specify a name (e.g.@: @code{a4}, @code{letter})
567 or measurements (e.g.@: @code{210x297}, @code{8.5x11in}).
569 The default paper size is taken from the @env{PAPERSIZE} environment
570 variable or the file indicated by the @env{PAPERCONF} environment
571 variable, if either variable is set. If not, and your system supports
572 the @code{LC_PAPER} locale category, then the default paper size is
573 taken from the locale. Otherwise, if @file{/etc/papersize} exists,
574 the default paper size is read from it. As a last resort, A4 paper is
577 @item orientation=@var{orientation}
579 Either @code{portrait} or @code{landscape}. Default: @code{portrait}.
581 @item left-margin=@var{dimension}
582 @itemx right-margin=@var{dimension}
583 @itemx top-margin=@var{dimension}
584 @itemx bottom-margin=@var{dimension}
586 Sets the margins around the page. The headers, if enabled, are not
587 included in the margins; they are in addition to the margins. For a
588 description of dimensions, see @ref{Dimensions}. Default: @code{0.5in}.
590 @item prop-font=@var{afm-file}[,@var{font-file}[,@var{encoding-file}]]
591 @itemx emph-font=@var{afm-file}[,@var{font-file}[,@var{encoding-file}]]
592 @itemx fixed-font=@var{afm-file}[,@var{font-file}[,@var{encoding-file}]]
594 Sets the font used for proportional, emphasized, or fixed-pitch text.
595 The only required value is @var{afm-file}, the AFM file for the font.
597 If specified, @var{font-file} will be downloaded to the printer at the
598 beginning of the print job. The font file may be in PFA or PFB format.
600 The font is reencoded as specified in @var{encoding-file}, if specified.
601 Each line in @var{encoding-file} should consist of a PostScript
602 character name and a decimal encoding value (between 0 and 255),
603 separated by white space. Blank lines and comments introduced by
604 @samp{#} are also allowed.
606 The files specified on these options are located as follows. If
607 the file name begins with @samp{/}, then it is taken as an absolute
608 path. Otherwise, PSPP searches its configuration path for the specified
609 name prefixed by @code{psfonts/} (@pxref{File locations}).
611 Default: proportional font @code{Times-Roman.afm}, emphasis font
612 @code{Times-Italic.afm}, fixed-pitch font @code{Courier.afm}.
614 @item font-size=@var{font-size}
616 Sets the size of the default fonts, in thousandths of a point. Default:
619 @item line-gutter=@var{dimension}
621 Sets the width of white space on either side of lines that border text
622 or graphics objects. @xref{Dimensions}. Default: @code{1pt}.
624 @item line-spacing=@var{dimension}
626 Sets the spacing between the lines in a double line in a table.
629 @item line-width=@var{dimension}
631 Sets the width of the lines used in tables. Default: @code{0.5pt}.
634 @node ASCII driver class
635 @section The ASCII driver class
637 The ASCII driver class produces output that can be displayed on a
638 terminal or output to printers. The ASCII driver has class name
641 The available options are listed below.
644 @item output-file=@var{file-name}
646 File to which output should be sent. This can be an ordinary file name
647 (e.g., @code{"pspp.txt"}), a pipe (e.g., @code{"|more"}), or
648 stdout (@code{"-"}). Default: @code{"pspp.list"}.
650 @item chart-files=@var{file-name-template}
651 Template for the file names used for charts. The name should contain
652 a single @samp{#}, which is replaced by the chart number. Default:
655 @item chart-type=@var{type}.
656 Type of charts to output. Available types typically include @samp{X},
657 @samp{png}, @samp{gif}, @samp{svg}, @samp{ps}, @samp{cgm}, @samp{fig},
658 @samp{pcl}, @samp{hpgl}, @samp{regis}, @samp{tek}, and @samp{meta}.
661 You may specify @samp{none} to disable chart output. Charts are also
662 disabled if your installation of PSPP was compiled without
665 @item paginate=@var{boolean}
667 If set, a formfeed will be written at the end of every page. Default:
670 @item tab-width=@var{tab-width-value}
672 The distance between tab stops for this device. If set to 0, tabs will
673 not be used in the output. Default: @code{8}.
675 @item headers=@var{boolean}
677 If enabled, two lines of header information giving title and subtitle,
678 page number, date and time, and PSPP version are printed at the top of
679 every page. These two lines are in addition to any top margin
680 requested. Default: @code{on}.
682 @item length=@var{line-count}
684 Physical length of a page. Headers and margins are subtracted from
685 this value. You may specify the number of lines as a number, or for
686 screen output you may specify @code{auto} to track the height of the
687 terminal as it changes. Default: @code{66}.
689 @item width=@var{character-count}
691 Physical width of a page. Margins are subtracted from this value.
692 You may specify the width as a number of characters, or for screen
693 output you may specify @code{auto} to track the width of the terminal
694 as it changes. Default: @code{79}.
696 @item top-margin=@var{top-margin-lines}
698 Length of the top margin, in lines. PSPP subtracts this value from
699 the page length. Default: @code{2}.
701 @item bottom-margin=@var{bottom-margin-lines}
703 Length of the bottom margin, in lines. PSPP subtracts this value from
704 the page length. Default: @code{2}.
706 @item box[@var{line-type}]=@var{box-chars}
708 The characters used for lines in tables produced by the ASCII driver can
709 be changed using this option. @var{line-type} is used to indicate which
710 type of line to change; @var{box-chars} is the character or string of
711 characters to use for this type of line.
713 @var{line-type} must be a 4-digit number. The digits are in the order
714 `right', `bottom', `left', `top'. The possibilities for each digit are:
732 Sets @samp{|} as the character to use for a single-width line with
733 bottom and top components.
737 Sets @samp{#} as the character to use for the intersection of four
738 double-width lines, one each from the top, bottom, left and right.
740 @item box[1100]="\xda"
742 Sets @samp{"\xda"}, which under MS-DOS is a box character suitable for
743 the top-left corner of a box, as the character for the intersection of
744 two single-width lines, one each from the right and bottom.
756 @*@code{box[0010]="-"}
757 @*@code{box[1010]="-"}
761 @*@code{box[0001]="|"}
762 @*@code{box[0101]="|"}
766 @*@code{box[0020]="="}
767 @*@code{box[2020]="="}
771 @*@code{box[0030]="="}
772 @*@code{box[3030]="="}
775 For all others, @samp{+} is used unless there are double lines or
776 special lines, in which case @samp{#} is used.
779 @item init=@var{init-string}
780 If set, this string is written at the beginning of each output file.
781 It can be used to initialize device features, e.g.@: to enable VT100
782 line-drawing characters.
784 @item emphasis=@var{emphasis-style}
786 How to emphasize text. Your choices are @code{bold}, @code{underline},
787 or @code{none}. Bold and underline emphasis are achieved with
788 overstriking, which may not be supported by all the software to which
789 you might pass the output.
792 @node HTML driver class
793 @section The HTML driver class
795 The @code{html} driver class is used to produce output for viewing in
796 tables-capable web browsers such as Emacs' w3-mode. Its configuration
797 is very simple. Currently, the output has a very plain format. In the
798 future, further work may be done on improving the output appearance.
800 There are only a few options:
803 @item output-file=@var{file-name}
805 File to which output should be sent. This can be an ordinary file name
806 (i.e., @code{"pspp.ps"}), a pipe (i.e., @code{"|lpr"}), or
807 stdout (@code{"-"}). Default: @file{"pspp.html"}.
809 @item chart-files=@var{file-name-template}
810 Template for the file names used for charts, which are output in PNG
811 format. The name should contain a single @samp{#}, which is replaced by
812 the chart number. Default: @file{"pspp-#.png"}.
815 @node Miscellaneous configuring
816 @section Miscellaneous configuration
818 The following environment variables can be used to further configure
824 Used to determine the user's home directory. No default value.
826 @item STAT_INCLUDE_PATH
828 Path used to find include files in PSPP syntax files. Defaults vary
829 across operating systems:
839 @file{$HOME/.pspp/include}
842 @file{/usr/local/lib/pspp/include}
845 @file{/usr/lib/pspp/include}
848 @file{/usr/local/share/pspp/include}
851 @file{/usr/share/pspp/include}
861 @file{C:\PSPP\INCLUDE}
873 The terminal type @code{termcap} or @code{ncurses} will use, if such
874 support was compiled into PSPP.
876 @item STAT_OUTPUT_INIT_FILE
878 The basename used to search for the driver definition file.
879 @xref{Output devices}. @xref{File locations}. Default: @code{devices}.
881 @item STAT_OUTPUT_INIT_PATH
883 The path used to search for the driver definition file.
884 @xref{File locations}. Default: the standard configuration path.
888 The directory in which PSPP stores its temporary files (used when sorting
889 cases or concatenating large numbers of cases).
890 Default: (UNIX) @file{/tmp}, (MS-DOS) @file{\}, (other OSes) empty string.
895 Under MS-DOS only, these variables are consulted after TMPDIR, in this