Cruft removal
[pspp-builds.git] / doc / configuring.texi
1 @node Configuration
2 @appendix Configuring PSPP
3 @cindex configuration
4 @cindex PSPP, configuring
5
6 This chapter describe how to configure PSPP for your system.
7
8 @menu
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.
18 @end menu
19
20 @node File locations
21 @section Locating configuration files
22
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
30 priority.
31
32 @node Configuration techniques
33 @section Configuration techniques
34
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.
38
39 @enumerate
40 @item
41 Syntax commands that modify settings, such as @cmd{SET}.  @xref{SET}.
42
43 @item
44 Command-line options.  @xref{Invocation}.
45
46 @item
47 PSPP-specific environment variable contents.  @xref{Environment
48 variables}.
49
50 @item
51 General environment variable contents.  @xref{Environment variables}.
52
53 @item
54 Configuration file contents.  @xref{Configuration files}.
55
56 @item
57 Fallback defaults.
58 @end enumerate
59
60 Some of the above may not apply to a particular setting.
61
62 @node Configuration files
63 @section Configuration files
64
65 Most configuration files have a common form:
66
67 @itemize @bullet
68 @item
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.
72
73 @item
74 Before anything else is done, trailing white space is removed.
75
76 @item
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.
79
80 @itemize @minus
81 @item
82 White space preceding the backslash is retained.
83
84 @item
85 This rule continues to be applied until the line read does not end in a
86 backslash.
87
88 @item
89 It is an error if the last line in the file ends in a backslash.
90 @end itemize
91
92 @item
93 Comments are introduced by an octothorpe (@samp{#}), and continue until the
94 end of the line.
95
96 @itemize @minus
97 @item
98 An octothorpe inside balanced pairs of double quotation marks (@samp{"})
99 or single quotation marks (@samp{'}) does not introduce a comment.
100
101 @item
102 The backslash character can be used inside balanced quotes of either
103 type to escape the following character as a literal character.  
104
105 (This is distinct from the use of a backslash as a line-splicing
106 character.)
107
108 @item
109 Line splicing takes place before comment removal.
110 @end itemize
111
112 @item
113 Blank lines, and lines that contain only white space, are ignored.
114 @end itemize
115
116 @node Environment variables
117 @section Environment variables
118
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:
123
124 @menu
125 * Environment substitutions::   How environment substitutions are made.
126 * Predefined variables::        A few variables are automatically defined.
127 @end menu
128
129 @node Environment substitutions
130 @subsection Environment substitutions
131
132 Much of the power of environment variables lies in the way that they may
133 be substituted into configuration files.  Variable substitutions are
134 described below.
135
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
139 take three forms:
140
141 @table @code
142 @item $@var{var}
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{@{}).
146
147 @item $@{@var{var}@}
148 Same as above, but @var{var} may contain any character (except
149 @samp{@}}).
150
151 @item $$
152 Replaced by a single dollar sign.
153 @end table
154
155 Undefined variables expand to a empty value.
156
157 @node Predefined variables
158 @subsection Predefined environment variables
159
160 There are two environment variables predefined for use in environment
161 substitutions:
162
163 @table @samp
164 @item VER
165 Defined as the version number of PSPP, as a string, in a format
166 something like @samp{0.9.4}.
167
168 @item ARCH
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.
173 @end table
174
175 Nothing prevents these values from being overridden, although it's a
176 good idea not to do so.
177
178 @node Output devices
179 @section Output devices
180
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}).
187
188 Lines in @file{devices} are divided into three categories, described
189 briefly in the table below:
190
191 @table @i
192 @item driver category definitions
193 Define a driver in terms of other drivers.
194
195 @item macro definitions
196 Define environment variables local to the output driver
197 configuration file.
198
199 @item device definitions
200 Describe the configuration of an output device.
201 @end table
202
203 The following sections further elaborate the contents of the
204 @file{devices} file.
205
206 @menu
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.
213 @end menu
214
215 @node Driver categories
216 @subsection Driver categories
217
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}).
224
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.
231
232 Categories may also be specified on the command line
233 (@pxref{Invocation}).
234
235 This is all you need to know about categories.  If you're still curious,
236 read on.
237
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
241 drivers.
242
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.
246
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.
251
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
255 is not enabled.
256
257 It is an error if the list is not empty when the end of @file{devices}
258 is reached.
259
260 @node Macro definitions
261 @subsection Macro definitions
262
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.
268
269 Please note the following nuances of macro usage:
270
271 @itemize @bullet
272 @item
273 For the purposes of this section, @dfn{macro} and @dfn{environment
274 variable} are synonyms.
275
276 @item
277 Macros may not take arguments.
278
279 @item
280 Macros may not recurse.
281
282 @item
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.
286
287 @item
288 Macros override other all environment variables of the same name (within
289 the scope of @file{devices}).
290
291 @item
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}.
295
296 @item
297 There are two predefined macros, whose values are determined at runtime:
298
299 @table @samp
300 @item viewwidth
301 Defined as the width of the console screen, in columns of text.
302
303 @item viewlength
304 Defined as the length of the console screen, in lines of text.
305 @end table
306 @end itemize
307
308 @node Device definitions
309 @subsection Driver definitions
310
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.
314
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:
320
321 @table @i
322 @item driver name
323 A unique identifier, used to determine whether to enable the driver.
324
325 @item class name
326 One of the predefined driver classes supported by PSPP.  The
327 currently supported driver classes include `postscript' and `ascii'.
328
329 @item device type(s)
330 Zero or more of the following keywords, delimited by spaces:
331
332 @table @code
333 @item screen
334
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
337 convenient.
338
339 @item printer
340
341 Indicates that the device is a printer.
342
343 @item listing
344
345 Indicates that the device is a listing file.
346 @end table
347
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
352 information.
353
354 @item options
355 An optional set of options to pass to the driver itself.  The exact
356 format for the options varies among drivers.
357 @end table
358
359 The driver is enabled if:
360
361 @enumerate
362 @item
363 Its driver name is specified on the command line, or
364
365 @item
366 It's in a category specified on the command line, or
367
368 @item
369 If no categories or driver names are specified on the command line, it
370 is in category @code{default}.
371 @end enumerate
372
373 For more information on driver names, see @ref{Driver categories}.
374
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.
379
380 Options are dependent on the driver.  See the driver descriptions for
381 details.
382
383 @node Dimensions
384 @subsection Dimensions
385
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}.
389
390 @itemize @bullet
391 @item
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
394 (@samp{25/2}).
395
396 @item 
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{}:
401
402 @table @code
403 @item in
404 inch (1 @code{in} = 2.54 @code{cm})
405
406 @item "
407 inch (1 @code{in} = 2.54 @code{cm})
408
409 @item pt
410 printer's point (1 @code{in} = 72.27 @code{pt})
411
412 @item pc
413 pica (12 @code{pt} = 1 @code{pc})
414
415 @item bp
416 PostScript point (1 @code{in} = 72 @code{bp})
417
418 @item cm
419 centimeter
420
421 @item mm
422 millimeter (10 @code{mm} = 1 @code{cm})
423
424 @item dd
425 didot point (1157 @code{dd} = 1238 @code{pt})
426
427 @item cc
428 cicero (1 @code{cc} = 12 @code{dd})
429
430 @item sp
431 scaled point (65536 @code{sp} = 1 @code{pt})
432 @end table
433
434 @item
435 If no explicit unit is given, PSPP attempts to guess the best unit:
436
437 @itemize @minus
438 @item
439 Numbers less than 50 are assumed to be in inches.
440
441 @item
442 Numbers 50 or greater are assumed to be in millimeters.
443 @end itemize
444 @end itemize
445
446 @node Distinguishing line types
447 @subsection How lines are divided into types
448
449 The lines in @file{devices} are distinguished in the following manner:
450
451 @enumerate
452 @item
453 Leading white space is removed.
454
455 @item
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
458 a macro definition.
459
460 @item
461 Otherwise, the line is scanned for the first instance of a colon
462 (@samp{:}) or an equals sign (@samp{=}).
463
464 @item
465 If a colon is encountered first, the line is processed as a driver
466 definition.
467
468 @item
469 Otherwise, if an equals sign is encountered, the line is processed as a
470 macro definition.
471
472 @item
473 Otherwise, the line is ill-formed.
474 @end enumerate
475
476 @node Tokenizing lines
477 @subsection How lines are divided into tokens
478
479 Each driver definition line is run through a simple tokenizer.  This
480 tokenizer recognizes two basic types of tokens.
481
482 The first type is an equals sign (@samp{=}).  Equals signs are both
483 delimiters between tokens and tokens in themselves.
484
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.
489
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:
494
495 @table @code
496 @item \'
497 A single-quote (@samp{'}).
498
499 @item \"
500 A double-quote (@samp{"}).
501
502 @item \?
503 A question mark (@samp{?}).  Included for hysterical raisins.
504
505 @item \\
506 A backslash (@samp{\}).
507
508 @item \a
509 Audio bell (ASCII 7).
510
511 @item \b
512 Backspace (ASCII 8).
513
514 @item \f
515 Formfeed (ASCII 12).
516
517 @item \n
518 New-line (ASCII 10)
519
520 @item \r
521 Carriage return (ASCII 13).
522
523 @item \t
524 Tab (ASCII 9).
525
526 @item \v
527 Vertical tab (ASCII 11).
528
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.
533
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.
538 @end table
539
540 Tokens, outside of quoted strings, are delimited by white space or equals
541 signs.
542
543 @node PostScript driver class
544 @section The PostScript driver class
545
546 The @code{postscript} driver class is used to produce output that is
547 acceptable to PostScript printers and other interpreters.
548
549 The available options are listed below.
550
551 @table @code
552 @item output-file=@var{file-name}
553
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"}.
557
558 @item headers=@var{boolean}
559
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:
562 @code{on}.
563
564 @item paper-size=@var{paper-size}
565
566 Paper size.  You may specify a name (e.g.@: @code{a4}, @code{letter})
567 or measurements (e.g.@: @code{210x297}, @code{8.5x11in}).
568
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
575 assumed.
576
577 @item orientation=@var{orientation}
578
579 Either @code{portrait} or @code{landscape}.  Default: @code{portrait}.
580
581 @item left-margin=@var{dimension}
582 @itemx right-margin=@var{dimension}
583 @itemx top-margin=@var{dimension}
584 @itemx bottom-margin=@var{dimension}
585
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}.
589
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}]]
593
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.
596
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.
599
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.
605
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}).
610
611 Default: proportional font @code{Times-Roman.afm}, emphasis font
612 @code{Times-Italic.afm}, fixed-pitch font @code{Courier.afm}.
613
614 @item font-size=@var{font-size}
615
616 Sets the size of the default fonts, in thousandths of a point.  Default:
617 10000 (10 point).
618
619 @item line-gutter=@var{dimension}
620
621 Sets the width of white space on either side of lines that border text
622 or graphics objects.  @xref{Dimensions}.  Default: @code{1pt}.
623
624 @item line-spacing=@var{dimension}
625
626 Sets the spacing between the lines in a double line in a table.
627 Default: @code{1pt}.
628
629 @item line-width=@var{dimension}
630
631 Sets the width of the lines used in tables.  Default: @code{0.5pt}.
632 @end table
633
634 @node ASCII driver class
635 @section The ASCII driver class
636
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
639 @samp{ascii}.
640
641 The available options are listed below.
642
643 @table @code
644 @item output-file=@var{file-name}
645
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"}.
649
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:
653 @file{"pspp-#.png"}.
654
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}.
659 Default: @samp{png}.
660
661 You may specify @samp{none} to disable chart output.  Charts are also
662 disabled if your installation of PSPP was compiled without
663 @code{libplot}.
664
665 @item paginate=@var{boolean}
666
667 If set, a formfeed will be written at the end of every page.  Default:
668 @code{on}.
669
670 @item tab-width=@var{tab-width-value}
671
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}.
674
675 @item headers=@var{boolean}
676
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}.
681
682 @item length=@var{line-count}
683
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}.
688
689 @item width=@var{character-count}
690
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}.
695
696 @item top-margin=@var{top-margin-lines}
697
698 Length of the top margin, in lines.  PSPP subtracts this value from
699 the page length.  Default: @code{2}.
700
701 @item bottom-margin=@var{bottom-margin-lines}
702
703 Length of the bottom margin, in lines.  PSPP subtracts this value from
704 the page length.  Default: @code{2}.
705
706 @item box[@var{line-type}]=@var{box-chars}
707
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.
712
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:
715
716 @table @asis
717 @item 0
718 No line.
719
720 @item 1
721 Single line.
722
723 @item 2
724 Double line.
725 @end table
726
727 Examples:
728
729 @table @code
730 @item box[0101]="|"
731
732 Sets @samp{|} as the character to use for a single-width line with
733 bottom and top components.
734
735 @item box[2222]="#"
736
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.
739
740 @item box[1100]="\xda"
741
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.
745
746 @end table
747
748 Defaults:
749
750 @itemize @bullet
751 @item
752 @code{box[0000]=" "}
753
754 @item
755 @code{box[1000]="-"}
756 @*@code{box[0010]="-"}
757 @*@code{box[1010]="-"}
758
759 @item
760 @code{box[0100]="|"}
761 @*@code{box[0001]="|"}
762 @*@code{box[0101]="|"}
763
764 @item
765 @code{box[2000]="="}
766 @*@code{box[0020]="="}
767 @*@code{box[2020]="="}
768
769 @item
770 @code{box[3000]="="}
771 @*@code{box[0030]="="}
772 @*@code{box[3030]="="}
773
774 @item
775 For all others, @samp{+} is used unless there are double lines or
776 special lines, in which case @samp{#} is used.
777 @end itemize
778
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.
783
784 @item emphasis=@var{emphasis-style}
785
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.
790 @end table
791
792 @node HTML driver class
793 @section The HTML driver class
794
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.
799
800 There are only a few options:
801
802 @table @code
803 @item output-file=@var{file-name}
804
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"}.
808
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"}.
813 @end table
814
815 @node Miscellaneous configuring
816 @section Miscellaneous configuration
817
818 The following environment variables can be used to further configure
819 PSPP:
820
821 @table @code
822 @item HOME
823
824 Used to determine the user's home directory.  No default value.
825
826 @item STAT_INCLUDE_PATH
827
828 Path used to find include files in PSPP syntax files.  Defaults vary
829 across operating systems:
830
831 @table @asis
832 @item UNIX
833
834 @itemize @bullet
835 @item
836 @file{.}
837
838 @item
839 @file{$HOME/.pspp/include}
840
841 @item
842 @file{/usr/local/lib/pspp/include}
843
844 @item
845 @file{/usr/lib/pspp/include}
846
847 @item
848 @file{/usr/local/share/pspp/include}
849
850 @item
851 @file{/usr/share/pspp/include}
852 @end itemize
853
854 @item MS-DOS
855
856 @itemize @bullet
857 @item
858 @file{.}
859
860 @item
861 @file{C:\PSPP\INCLUDE}
862
863 @item
864 @file{$PATH}
865 @end itemize
866
867 @item Other OSes
868 No default path.
869 @end table
870
871 @item TERM
872
873 The terminal type @code{termcap} or @code{ncurses} will use, if such
874 support was compiled into PSPP.
875
876 @item STAT_OUTPUT_INIT_FILE
877
878 The basename used to search for the driver definition file.
879 @xref{Output devices}.  @xref{File locations}.  Default: @code{devices}.
880
881 @item STAT_OUTPUT_INIT_PATH
882
883 The path used to search for the driver definition file.
884 @xref{File locations}.  Default: the standard configuration path.
885
886 @item TMPDIR
887
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.
891
892 @item TEMP
893 @item TMP
894
895 Under MS-DOS only, these variables are consulted after TMPDIR, in this
896 order.
897 @end table