1 This is pspp.info, produced by makeinfo version 4.0 from pspp.texi.
4 * PSPP: (pspp). Statistical analysis package.
7 PSPP, for statistical analysis of sampled data, by Ben Pfaff.
9 This file documents PSPP, a statistical package for analysis of
10 sampled data that uses a command language compatible with SPSS.
12 Copyright (C) 1996-9, 2000 Free Software Foundation, Inc.
14 This version of the PSPP documentation is consistent with version 2
17 Permission is granted to make and distribute verbatim copies of this
18 manual provided the copyright notice and this permission notice are
19 preserved on all copies.
21 Permission is granted to copy and distribute modified versions of
22 this manual under the conditions for verbatim copying, provided that the
23 entire resulting derived work is distributed under the terms of a
24 permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above condition for modified
28 versions, except that this permission notice may be stated in a
29 translation approved by the Free Software Foundation.
32 File: pspp.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
37 This file documents the PSPP package for statistical analysis of
38 sampled data. This is edition 0.2, for PSPP version 0.2, last modified
39 at Time-stamp: <2000-01-02 22:32:14 blp>.
43 * Introduction:: Description of the package.
44 * License:: Your rights and obligations.
45 * Credits:: Acknowledgement of authors.
47 * Installation:: How to compile and install PSPP.
48 * Configuration:: Configuring PSPP.
49 * Invocation:: Starting and running PSPP.
51 * Language:: Basics of the PSPP command language.
52 * Expressions:: Numeric and string expression syntax.
54 * Data Input and Output:: Reading data from user files.
55 * System and Portable Files:: Dealing with system & portable files.
56 * Variable Attributes:: Adjusting and examining variables.
57 * Data Manipulation:: Simple operations on data.
58 * Data Selection:: Select certain cases for analysis.
59 * Conditionals and Looping:: Doing things many times or not at all.
60 * Statistics:: Basic statistical procedures.
61 * Utilities:: Other commands.
62 * Not Implemented:: What's not here yet
64 * Data File Format:: Format of PSPP system files.
65 * Portable File Format:: Format of PSPP portable files.
66 * q2c Input Format:: Format of syntax accepted by q2c.
68 * Bugs:: Known problems; submitting bug reports.
70 * Function Index:: Index of PSPP functions for expressions.
71 * Concept Index:: Index of concepts.
72 * Command Index:: Index of PSPP procedures.
75 File: pspp.info, Node: Introduction, Next: License, Prev: Top, Up: Top
80 PSPP is a tool for statistical analysis of sampled data. It reads a
81 syntax file and a data file, analyzes the data, and writes the results
82 to a listing file or to standard output.
84 The language accepted by PSPP is similar to those accepted by SPSS
85 statistical products. The details of PSPP's language are given later
88 PSPP produces output in two forms: tables and charts. Both of these
89 can be written in several formats; currently, ASCII, PostScript, and
90 HTML are supported. In the future, more drivers, such as PCL and X
91 Window System drivers, may be developed. For now, Ghostscript,
92 available from the Free Software Foundation, may be used to convert
93 PostScript chart output to other formats.
95 The current version of PSPP, 0.2, is woefully incomplete in terms of
96 its statistical procedure support. PSPP is a work in progress. The
97 author hopes to support fully support all features in the products that
98 PSPP replaces, eventually. The author welcomes questions, comments,
99 donations, and code submissions. *Note Submitting Bug Reports: Bugs,
100 for instructions on contacting the author.
103 File: pspp.info, Node: License, Next: Credits, Prev: Introduction, Up: Top
105 Your rights and obligations
106 ***************************
108 Most of PSPP is distributed under the GNU General Public License.
109 The General Public License says, in effect, that you may modify and
110 distribute PSPP as you like, as long as you grant the same rights to
111 others. It also states that you must provide source code when you
112 distribute PSPP, or, if you obtained PSPP source code from an anonymous
113 ftp site, give out the name of that site.
115 The General Public License is given in full in the source
116 distribution as file `COPYING'. In Debian GNU/Linux, this file is also
117 available as file `/usr/doc/copyright/GPL'.
119 To quote the GPL itself:
121 This program is free software; you can redistribute it and/or
122 modify it under the terms of the GNU General Public License as
123 published by the Free Software Foundation; either version 2 of the
124 License, or (at your option) any later version.
126 This program is distributed in the hope that it will be useful, but
127 WITHOUT ANY WARRANTY; without even the implied warranty of
128 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
129 General Public License for more details.
131 You should have received a copy of the GNU General Public License
132 along with this program; if not, write to the Free Software
133 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
136 File: pspp.info, Node: Credits, Next: Installation, Prev: License, Up: Top
141 I'm always embarrassed when I see an index an author has made of
142 his own work. It's a shameless exhibition--to the trained eye.
143 Never index your own book.
145 --Claire Minton, `Cat's Cradle', Kurt Vonnegut, Jr.
147 Most of PSPP, as well as this manual (including the indices), was
148 written by Ben Pfaff. *Note Contacting the Author::, for instructions
149 on contacting the author.
151 The PSPP source code incorporates `julcal10' originally written by
152 Michael A. Covington and translated into C by Jim Van Zandt. The
153 original package can be found in directory
154 `ftp://ftp.cdrom.com/pub/algorithms/c/julcal10'. The entire contents
155 of that directory constitute the package. The files actually used in
156 PSPP are `julcal.c' and `julcal.h'.
159 File: pspp.info, Node: Installation, Next: Configuration, Prev: Credits, Up: Top
164 PSPP conforms to the GNU Coding Standards. PSPP is written in, and
165 requires for proper operation, ANSI/ISO C. You might want to
166 additionally note the following points:
168 * The compiler and linker must allow for significance of several
169 characters in external identifiers. The exact number is unknown
170 but at least 31 is recommended.
172 * The `int' type must be 32 bits or wider.
174 * The recommended compiler is gcc 2.7.2.1 or later, but any ANSI
175 compiler will do if it fits the above criteria.
177 Many UNIX variants should work out-of-the-box, as PSPP uses GNU
178 autoconf to detect differences between environments. Please report any
179 problems with compilation of PSPP under UNIX and UNIX-like operating
180 systems--portability is a major concern of the author.
182 The pages below give specific instructions for installing PSPP on
183 each type of system mentioned above.
187 * UNIX installation:: Installing on UNIX-like environments.
190 File: pspp.info, Node: UNIX installation, Prev: Installation, Up: Installation
195 To install PSPP under a UNIX-like operating system, follow the steps
196 below in order. Some of the text below was taken directly from various
197 Free Software Foundation sources.
199 1. `cd' to the directory containing the PSPP source.
201 2. Type `./configure' to configure for your particular operating
202 system and compiler. Running `configure' takes a while. While
203 running, it displays some messages telling which features it is
206 You can optionally supply some options to `configure' in order to
207 give it hints about how to do its job. Type `./configure --help'
208 to see a list of options. One of the most useful options is
209 `--with-checker', which enables the use of the Checker memory
210 debugger under supported operating systems. Checker must already
211 be installed to use this option. Do not use `--with-checker' if
212 you are not debugging PSPP itself.
214 3. (optional) Edit `Makefile', `config.h', and `pref.h'. These files
215 are produced by `configure'. Note that most PSPP settings can be
218 `pref.h' is only generated by `configure' if it does not already
219 exist. (It's copied from `prefh.orig'.)
221 4. Type `make' to compile the package. If there are any errors during
222 compilation, try to fix them. If modifications are necessary to
223 compile correctly under your configuration, contact the author.
224 *Note Submitting Bug Reports: Bugs, for details.
226 5. Type `make check' to run self-tests on the compiled PSPP package.
228 6. Become the superuser and type `make install' to install the PSPP
229 binaries, by default in `/usr/local/bin/'. The directory
230 `/usr/local/share/pspp/' is created and populated with files
231 needed by PSPP at runtime. This step will also cause the PSPP
232 documentation to be installed in `/usr/local/info/', but only if
233 that directory already exists.
235 7. (optional) Type `make clean' to delete the PSPP binaries from the
239 File: pspp.info, Node: Configuration, Next: Invocation, Prev: Installation, Up: Top
244 PSPP has dozens of configuration possibilities and hundreds of
245 settings. This is both a bane and a blessing. On one hand, it's
246 possible to easily accommodate diverse ranges of setups. But, on the
247 other, the multitude of possibilities can overwhelm the casual user.
248 Fortunately, the configuration mechanisms are profusely described in the
253 * File locations:: How PSPP finds config files.
254 * Configuration techniques:: Many different methods of configuration....
255 * Configuration files:: How configuration files are read.
256 * Environment variables:: All about environment variables.
257 * Output devices:: Describing your terminal(s) and printer(s).
258 * PostScript driver class:: Configuration of PostScript devices.
259 * ASCII driver class:: Configuration of character-code devices.
260 * HTML driver class:: Configuration for HTML output.
261 * Miscellaneous configuring:: Even more configuration variables.
262 * Improving output quality:: Hints for producing ever-more-lovely output.
265 File: pspp.info, Node: File locations, Next: Configuration techniques, Prev: Configuration, Up: Configuration
267 Locating configuration files
268 ============================
270 PSPP uses the same method to find most of its configuration files:
272 1. The "base name" of the file being sought is determined.
274 2. The path to search is determined.
276 3. Each directory in the search path, from left to right, is searched
277 for a file with the name of the base name. The first occurrence
278 is read as the configuration file.
280 The first two steps are elaborated below for the sake of our pedantic
283 1. A "base name" is a file name lacking an absolute directory
284 reference. Some examples of base names are: `ps-encodings',
285 `devices', `devps/DESC' (under UNIX), `devps\DESC' (under M$
288 Determining the base name is a two-step process:
290 a. If the appropriate environment variable is defined, the value
291 of that variable is used (*note Environment variables::).
292 For instance, when searching for the output driver
293 initialization file, the variable examined is
294 `STAT_OUTPUT_INIT_FILE'.
296 b. Otherwise, the compiled-in default is used. For example,
297 when searching for the output driver initialization file, the
298 default base name is `devices'.
300 *Please note:* If a user-specified base name does contain an
301 absolute directory reference, as in a file name like
302 `/home/pfaff/fonts/TR', no path is searched--the file name is used
303 exactly as given--and the algorithm terminates.
305 2. The path is the first of the following that is defined:
307 * A variable definition for the path given in the user
308 environment. This is a PSPP-specific environment variable
309 name; for instance, `STAT_OUTPUT_INIT_PATH'.
311 * In some cases, another, less-specific environment variable is
312 checked. For instance, when searching for font files, the
313 PostScript driver first checks for a variable with name
314 `STAT_GROFF_FONT_PATH', then for one with name
315 `GROFF_FONT_PATH'. (However, font searching has its own list
316 of esoteric search rules.)
318 * The configuration file path, which is itself determined by the
321 a. If the command line contains an option of the form `-B
322 PATH' or `--config-dir=PATH', then the value given on the
323 rightmost occurrence of such an option is used.
325 b. Otherwise, if the environment variable
326 `STAT_CONFIG_PATH' is defined, the value of that
329 c. Otherwise, the compiled-in fallback default is used. On
330 UNIX machines, the default fallback path is
334 2. `/usr/local/lib/pspp'
338 On DOS machines, the default fallback path is:
340 1. All the paths from the DOS search path in the
341 `PATH' environment variable, in left-to-right order.
343 2. `C:\PSPP', as a last resort.
345 Note that the installer of PSPP can easily change this
346 default fallback path; thus the above should not be
349 As a final note: Under DOS, directories given in paths are delimited
350 by semicolons (`;'); under UNIX, directories are delimited by colons
351 (`:'). This corresponds with the standard path delimiter under these
355 File: pspp.info, Node: Configuration techniques, Next: Configuration files, Prev: File locations, Up: Configuration
357 Configuration techniques
358 ========================
360 There are many ways that PSPP can be configured. These are
361 described in the list below. Values given by earlier items take
362 precedence over those given by later items.
364 1. Syntax commands that modify settings, such as `SET'.
366 2. Command-line options. *Note Invocation::.
368 3. PSPP-specific environment variable contents. *Note Environment
371 4. General environment variable contents. *Note Environment
374 5. Configuration file contents. *Note Configuration files::.
376 6. Fallback defaults.
378 Some of the above may not apply to a particular setting. For
379 instance, the current pager (such as `more', `most', or `less') cannot
380 be determined by configuration file contents because there is no
381 appropriate configuration file.
384 File: pspp.info, Node: Configuration files, Next: Environment variables, Prev: Configuration techniques, Up: Configuration
389 Most configuration files have a common form:
391 * Each line forms a separate command or directive. This means that
392 lines cannot be broken up, unless they are spliced together with a
393 trailing backslash, as described below.
395 * Before anything else is done, trailing whitespace is removed.
397 * When a line ends in a backslash (`\'), the backslash is removed,
398 and the next line is read and appended to the current line.
400 - Whitespace preceding the backslash is retained.
402 - This rule continues to be applied until the line read does
403 not end in a backslash.
405 - It is an error if the last line in the file ends in a
408 * Comments are introduced by an octothorpe (#), and continue until
411 - An octothorpe inside balanced pairs of double quotation marks
412 (`"') or single quotation marks (`'') does not introduce a
415 - The backslash character can be used inside balanced quotes of
416 either type to escape the following character as a literal
419 (This is distinct from the use of a backslash as a
420 line-splicing character.)
422 - Line splicing takes place before comment removal.
424 * Blank lines, and lines that contain only whitespace, are ignored.
427 File: pspp.info, Node: Environment variables, Next: Output devices, Prev: Configuration files, Up: Configuration
429 Environment variables
430 =====================
432 You may think the concept of environment variables is a fairly simple
433 one. However, the author of PSPP has found a way to complicate even
434 something so simple. Environment variables are further described in
439 * Variable values:: Values of variables are determined this way.
440 * Environment substitutions:: How environment substitutions are made.
441 * Predefined variables:: A few variables are automatically defined.
444 File: pspp.info, Node: Variable values, Next: Environment substitutions, Prev: Environment variables, Up: Environment variables
446 Values of environment variables
447 -------------------------------
449 Values for environment variables are obtained by the following means,
450 which are arranged in order of decreasing precedence:
452 1. Command-line options. *Note Invocation::.
454 2. The `environment' configuration file--more on this below.
456 3. Actual environment variables (defined in the shell or other parent
459 The `environment' configuration file is located through application
460 of the usual algorithm for configuration files (*note File locations::),
461 except that its contents do not affect the search path used to find
462 `environment' itself. Use of `environment' is discouraged on systems
463 that allow an arbitrarily large environment; it is supported for use on
464 systems like MS-DOS that limit environment size.
466 `environment' is composed of lines having the form `KEY=VALUE',
467 where KEY and the equals sign (`=') are required, and VALUE is
468 optional. If VALUE is given, variable KEY is given that value; if
469 VALUE is absent, variable KEY is undefined (deleted). Variables may
470 not be defined with a null value.
472 Environment substitutions are performed on each line in the file
473 (*note Environment substitutions::).
475 See *Note Configuration files::, for more details on formatting of
476 the environment configuration file.
478 *Please note:* Support for `environment' is not yet implemented.
481 File: pspp.info, Node: Environment substitutions, Next: Predefined variables, Prev: Variable values, Up: Environment variables
483 Environment substitutions
484 -------------------------
486 Much of the power of environment variables lies in the way that they
487 may be substituted into configuration files. Variable substitutions are
490 The line is scanned from left to right. In this scan, all characters
491 other than dollar signs (`$') are retained unmolested. Dollar signs,
492 however, introduce an environment variable reference. References take
496 Replaced by the value of environment variable VAR, determined as
497 specified in *Note Variable values::. VAR must be one of the
500 * One or more letters.
502 * Exactly one nonalphabetic character. This may not be a left
506 Same as above, but VAR may contain any character (except `}').
509 Replaced by a single dollar sign.
511 Undefined variables expand to a empty value.
514 File: pspp.info, Node: Predefined variables, Prev: Environment substitutions, Up: Environment variables
516 Predefined environment variables
517 --------------------------------
519 There are two environment variables predefined for use in environment
523 Defined as the version number of PSPP, as a string, in a format
524 something like `0.9.4'.
527 Defined as the host architecture of PSPP, as a string, in standard
528 cpu-manufacturer-OS format. For instance, Debian GNU/Linux 1.1 on
529 an Intel machine defines this as `i586-unknown-linux'. This is
530 somewhat dependent on the system used to compile PSPP.
532 Nothing prevents these values from being overridden, although it's a
533 good idea not to do so.
536 File: pspp.info, Node: Output devices, Next: PostScript driver class, Prev: Environment variables, Up: Configuration
541 Configuring output devices is the most complicated aspect of
542 configuring PSPP. The output device configuration file is named
543 `devices'. It is searched for using the usual algorithm for finding
544 configuration files (*note File locations::). Each line in the file is
545 read in the usual manner for configuration files (*note Configuration
548 Lines in `devices' are divided into three categories, described
549 briefly in the table below:
551 driver category definitions
552 Define a driver in terms of other drivers.
555 Define environment variables local to the the output driver
559 Describe the configuration of an output device.
561 The following sections further elaborate the contents of the
566 * Driver categories:: How to organize the driver namespace.
567 * Macro definitions:: Environment variables local to `devices'.
568 * Device definitions:: Output device descriptions.
569 * Dimensions:: Lengths, widths, sizes, ....
570 * papersize:: Letter, legal, A4, envelope, ....
571 * Distinguishing line types:: Details on `devices' parsing.
572 * Tokenizing lines:: Dividing `devices' lines into tokens.
575 File: pspp.info, Node: Driver categories, Next: Macro definitions, Prev: Output devices, Up: Output devices
580 Drivers can be divided into categories. Drivers are specified by
581 their names, or by the names of the categories that they are contained
582 in. Only certain drivers are enabled each time PSPP is run; by
583 default, these are the drivers in the category `default'. To enable a
584 different set of drivers, use the `-o DEVICE' command-line option
585 (*note Invocation::).
587 Categories are specified with a line of the form `CATEGORY=DRIVER1
588 DRIVER2 DRIVER3 ... DRIVERN'. This line specifies that the category
589 CATEGORY is composed of drivers named DRIVER1, DRIVER2, and so on.
590 There may be any number of drivers in the category, from zero on up.
592 Categories may also be specified on the command line (*note
595 This is all you need to know about categories. If you're still
598 First of all, the term `categories' is a bit of a misnomer. In fact,
599 the internal representation is nothing like the hierarchy that the term
600 seems to imply: a linear list is used to keep track of the enabled
603 When PSPP first begins reading `devices', this list contains the
604 name of any drivers or categories specified on the command line, or the
605 single item `default' if none were specified.
607 Each time a category definition is specified, the list is searched
608 for an item with the value of CATEGORY. If a matching item is found,
609 it is deleted. If there was a match, the list of drivers (DRIVER1
610 through DRIVERN) is then appended to the list.
612 Each time a driver definition line is encountered, the list is
613 searched. If the list contains an item with that driver's name, the
614 driver is enabled and the item is deleted from the list. Otherwise,
615 the driver is not enabled.
617 It is an error if the list is not empty when the end of `devices' is
621 File: pspp.info, Node: Macro definitions, Next: Device definitions, Prev: Driver categories, Up: Output devices
626 Macro definitions take the form `define MACRONAME DEFINITION'. In
627 such a macro definition, the environment variable MACRONAME is defined
628 to expand to the value DEFINITION. Before the definition is made,
629 however, any macros used in DEFINITION are expanded.
631 Please note the following nuances of macro usage:
633 * For the purposes of this section, "macro" and "environment
634 variable" are synonyms.
636 * Macros may not take arguments.
638 * Macros may not recurse.
640 * Macros are just environment variable definitions like other
641 environment variable definitions, with the exception that they are
642 limited in scope to the `devices' configuration file.
644 * Macros override other all environment variables of the same name
645 (within the scope of `devices').
647 * Earlier macro definitions for a particular KEY override later
648 ones. In particular, macro definitions on the command line
649 override those in the device definition file. *Note Non-option
652 * There are two predefined macros, whose values are determined at
656 Defined as the width of the console screen, in columns of
660 Defined as the length of the console screen, in lines of text.
663 File: pspp.info, Node: Device definitions, Next: Dimensions, Prev: Macro definitions, Up: Output devices
668 Driver definitions are the ultimate purpose of the `devices'
669 configuration file. These are where the real action is. Driver
670 definitions tell PSPP where it should send its output.
672 Each driver definition line is divided into four fields. These
673 fields are delimited by colons (`:'). Each line is subjected to
674 environment variable interpolation before it is processed further
675 (*note Environment substitutions::). From left to right, the four
676 fields are, in brief:
679 A unique identifier, used to determine whether to enable the
683 One of the predefined driver classes supported by PSPP. The
684 currently supported driver classes include `postscript' and
688 Zero or more of the following keywords, delimited by spaces:
691 Indicates that the device is a screen display. This may
692 reduce the amount of buffering done by the driver, to make
693 interactive use more convenient.
696 Indicates that the device is a printer.
699 Indicates that the device is a listing file.
701 These options are just hints to PSPP and do not cause the output
702 to be directed to the screen, or to the printer, or to a listing
703 file--those must be set elsewhere in the options. They are used
704 primarily to decide which devices should be enabled at any given
705 time. *Note SET::, for more information.
708 An optional set of options to pass to the driver itself. The exact
709 format for the options varies among drivers.
711 The driver is enabled if:
713 1. Its driver name is specified on the command line, or
715 2. It's in a category specified on the command line, or
717 3. If no categories or driver names are specified on the command
718 line, it is in category `default'.
720 For more information on driver names, see *Note Driver categories::.
722 The class name must be one of those supported by PSPP. The classes
723 supported depend on the options with which PSPP was compiled. See
724 later sections in this chapter for descriptions of the available driver
727 Options are dependent on the driver. See the driver descriptions for
731 File: pspp.info, Node: Dimensions, Next: papersize, Prev: Device definitions, Up: Output devices
736 Quite often in configuration it is necessary to specify a length or a
737 size. PSPP uses a common syntax for all such, calling them
738 collectively by the name "dimensions".
740 * You can specify dimensions in decimal form (`12.5') or as
741 fractions, either as mixed numbers (`12-1/2') or raw fractions
744 * A number of different units are available. These are suffixed to
745 the numeric part of the dimension. There must be no spaces
746 between the number and the unit. The available units are
747 identical to those offered by the popular typesetting system TeX:
750 inch (1 `in' = 2.54 `cm')
753 inch (1 `in' = 2.54 `cm')
756 printer's point (1 `in' = 72.27 `pt')
759 pica (12 `pt' = 1 `pc')
762 PostScript point (1 `in' = 72 `bp')
768 millimeter (10 `mm' = 1 `cm')
771 didot point (1157 `dd' = 1238 `pt')
774 cicero (1 `cc' = 12 `dd')
777 scaled point (65536 `sp' = 1 `pt')
779 * If no explicit unit is given, a DWIM(1) "feature" attempts to
782 - Numbers less than 50 are assumed to be in inches.
784 - Numbers 50 or greater are assumed to be in millimeters.
786 ---------- Footnotes ----------
791 File: pspp.info, Node: papersize, Next: Distinguishing line types, Prev: Dimensions, Up: Output devices
796 Output drivers usually deal with some sort of hardcopy media. This
797 media is called "paper" by the drivers, though in reality it could be a
798 transparency or film or thinly veiled sarcasm. To make it easier for
799 you to deal with paper, PSPP allows you to have (of course!) a
800 configuration file that gives symbolic names, like "letter" or "legal"
801 or "a4", to paper sizes, rather than forcing you to use cryptic numbers
802 like "8-1/2 x 11" or "210 by 297". Surprisingly enough, this
803 configuration file is named `papersize'. *Note Configuration files::.
805 When PSPP tries to connect a symbolic paper name to a paper size, it
806 reads and parses each non-comment line in the file, in order. The first
807 field on each line must be a symbolic paper name in double quotes.
808 Paper names may not contain double quotes. Paper names are not
809 case-sensitive: `legal' and `Legal' are equivalent.
811 If a match is found for the paper name, the rest of the line is
812 parsed. If it is found to be a pair of dimensions (*note Dimensions::)
813 separated by either `x' or `by', then those are taken to be the paper
814 size, in order of width followed by length. There _must_ be at least
815 one space on each side of `x' or `by'.
817 Otherwise the line must be of the form `"PAPER-1"="PAPER-2"'. In
818 this case the target of the search becomes paper name PAPER-2 and the
819 search through the file continues.
822 File: pspp.info, Node: Distinguishing line types, Next: Tokenizing lines, Prev: papersize, Up: Output devices
824 How lines are divided into types
825 --------------------------------
827 The lines in `devices' are distinguished in the following manner:
829 1. Leading whitespace is removed.
831 2. If the resulting line begins with the exact string `define',
832 followed by one or more whitespace characters, the line is
833 processed as a macro definition.
835 3. Otherwise, the line is scanned for the first instance of a colon
836 (`:') or an equals sign (`=').
838 4. If a colon is encountered first, the line is processed as a driver
841 5. Otherwise, if an equals sign is encountered, the line is processed
842 as a macro definition.
844 6. Otherwise, the line is ill-formed.
847 File: pspp.info, Node: Tokenizing lines, Prev: Distinguishing line types, Up: Output devices
849 How lines are divided into tokens
850 ---------------------------------
852 Each driver definition line is run through a simple tokenizer. This
853 tokenizer recognizes two basic types of tokens.
855 The first type is an equals sign (`='). Equals signs are both
856 delimiters between tokens and tokens in themselves.
858 The second type is an identifier or string token. Identifiers and
859 strings are equivalent after tokenization, though they are written
860 differently. An identifier is any string of characters other than
861 whitespace or equals sign.
863 A string is introduced by a single- or double-quote character (`''
864 or `"') and, in general, continues until the next occurrence of that
865 same character. The following standard C escapes can also be embedded
869 A single-quote (`'').
872 A double-quote (`"').
875 A question mark (`?'). Included for hysterical raisins.
881 Audio bell (ASCII 7).
893 Carriage return (ASCII 13).
899 Vertical tab (ASCII 11).
902 Each `o' must be an octal digit. The character is the one having
903 the octal value specified. Any number of octal digits is read and
904 interpreted; only the lower 8 bits are used.
907 Each `h' must be a hex digit. The character is the one having the
908 hexadecimal value specified. Any number of hex digits is read and
909 interpreted; only the lower 8 bits are used.
911 Tokens, outside of quoted strings, are delimited by whitespace or
915 File: pspp.info, Node: PostScript driver class, Next: ASCII driver class, Prev: Output devices, Up: Configuration
917 The PostScript driver class
918 ===========================
920 The `postscript' driver class is used to produce output that is
921 acceptable to PostScript printers and to PC-based PostScript
922 interpreters such as Ghostscript. Continuing a long tradition, PSPP's
923 PostScript driver is configurable to the point of absurdity.
925 There are actually two PostScript drivers. The first one,
926 `postscript', produces ordinary DSC-compliant PostScript output. The
927 second one `epsf', produces an Encapsulated PostScript file. The two
928 drivers are otherwise identical in configuration and in operation.
930 The PostScript driver is described in further detail below.
934 * PS output options:: Output file options.
935 * PS page options:: Paper, margins, scaling & rotation, more!
936 * PS file options:: Configuration files.
937 * PS font options:: Default fonts, font options.
938 * PS line options:: Line widths, options.
939 * Prologue:: Details on the PostScript prologue.
940 * Encodings:: Details on PostScript font encodings.
943 File: pspp.info, Node: PS output options, Next: PS page options, Prev: PostScript driver class, Up: PostScript driver class
945 PostScript output options
946 -------------------------
948 These options deal with the form of the output and the output file
951 `output-file=FILENAME'
952 File to which output should be sent. This can be an ordinary
953 filename (i.e., `"pspp.ps"'), a pipe filename (i.e., `"|lpr"'), or
954 stdout (`"-"'). Default: `"pspp.ps"'.
957 Most of the time black-and-white PostScript devices are smart
958 enough to map colors to shades themselves. However, you can cause
959 the PSPP output driver to do an ugly simulation of this in its own
960 driver by turning `color' off. Default: `on'.
962 This is a boolean setting, as are many settings in the PostScript
963 driver. Valid positive boolean values are `on', `true', `yes',
964 and nonzero integers. Negative boolean values are `off', `false',
968 One of `clean7bit', `clean8bit', or `binary'. This controls what
969 characters will be written to the output file. PostScript
970 produced with `clean7bit' can be transmitted over 7-bit
971 transmission channels that use ASCII control characters for line
972 control. `clean8bit' is similar but allows characters above 127 to
973 be written to the output file. `binary' allows any character in
974 the output file. Default: `clean7bit'.
976 `line-ends=LINE-END-TYPE'
977 One of `cr', `lf', or `crlf'. This controls what is used for
978 newline in the output file. Default: `cr'.
980 `optimize-line-size=LEVEL'
981 Either `0' or `1'. If LEVEL is `1', then short line segments will
982 be collected and merged into longer ones. This reduces output
983 file size but requires more time and memory. A LEVEL of `0' has
984 the advantage of being better for interactive environments. `1'
985 is the default unless the `screen' flag is set; in that case, the
988 `optimize-text-size=LEVEL'
989 One of `0', `1', or `2', each higher level representing
990 correspondingly more aggressive space savings for text in the
991 output file and requiring correspondingly more time and memory.
992 Unfortunately the levels presently are all the same. `1' is the
993 default unless the `screen' flag is set; in that case, the default
997 File: pspp.info, Node: PS page options, Next: PS file options, Prev: PS output options, Up: PostScript driver class
999 PostScript page options
1000 -----------------------
1002 These options affect page setup:
1005 Controls whether the standard headers showing the time and date and
1006 title and subtitle are printed at the top of each page. Default:
1009 `paper-size=PAPER-SIZE'
1010 Paper size, either as a symbolic name (i.e., `letter' or `a4') or
1011 specific measurements (i.e., `8-1/2x11' or `"210 x 297"'. *Note
1012 Paper sizes: papersize. Default: `letter'.
1014 `orientation=ORIENTATION'
1015 Either `portrait' or `landscape'. Default: `portrait'.
1017 `left-margin=DIMENSION'
1018 `right-margin=DIMENSION'
1019 `top-margin=DIMENSION'
1020 `bottom-margin=DIMENSION'
1021 Sets the margins around the page. The headers, if enabled, are not
1022 included in the margins; they are in addition to the margins. For
1023 a description of dimensions, see *Note Dimensions::. Default:
1027 File: pspp.info, Node: PS file options, Next: PS font options, Prev: PS page options, Up: PostScript driver class
1029 PostScript file options
1030 -----------------------
1032 Oh, my. You don't really want to know about the way that the
1033 PostScript driver deals with files, do you? Well I suppose you're
1034 entitled, but I warn you right now: it's not pretty. Here goes....
1036 First let's look at the options that are available:
1038 `font-dir=FONT-DIRECTORY'
1039 Sets the font directory. Default: `devps'.
1041 `prologue-file=PROLOGUE-FILE-NAME'
1042 Sets the name of the PostScript prologue file. You can write your
1043 own prologue, though I have no idea why you'd want to: see *Note
1044 Prologue::. Default: `ps-prologue'.
1046 `device-file=DEVICE-FILE-NAME'
1047 Sets the name of the Groff-format device description file. The
1048 PostScript driver reads this in order to know about the scaling of
1049 fonts and so on. The format of such files is described in
1050 groff_font(5), included with Groff. Default: `DESC'.
1052 `encoding-file=ENCODING-FILE-NAME'
1053 Sets the name of the encoding file. This file contains a list of
1054 all font encodings that will be needed so that the driver can put
1055 all of them at the top of the prologue. *Note Encodings::.
1056 Default: `ps-encodings'.
1058 If the specified encoding file cannot be found, this error will be
1059 silently ignored, since most people do not need any encodings
1060 besides the ones that can be found using `auto-encodings',
1063 `auto-encode=BOOLEAN'
1064 When enabled, the font encodings needed by the default
1065 proportional- and fixed-pitch fonts will automatically be dumped
1066 to the PostScript output. Otherwise, it is assumed that the user
1067 has an encoding file and knows how to use it (*note Encodings::).
1068 There is probably no good reason to turn off this convenient
1069 feature. Default: `on'.
1071 Next I suppose it's time to describe the search algorithm. When the
1072 PostScript driver needs a file, whether that file be a font, a
1073 PostScript prologue, or what you will, it searches in this manner:
1075 1. Constructs a path by taking the first of the following that is
1078 a. Environment variable `STAT_GROFF_FONT_PATH'. *Note
1079 Environment variables::.
1081 b. Environment variable `GROFF_FONT_PATH'.
1083 c. The compiled-in fallback default.
1085 2. Constructs a base name from concatenating, in order, the font
1086 directory, a path separator (`/' or `\'), and the file to be
1087 found. A typical base name would be something like
1088 `devps/ps-encodings'.
1090 3. Searches for the base name in the path constructed above. If the
1091 file is found, the algorithm terminates.
1093 4. Searches for the base name in the standard configuration path. See
1094 *Note File locations::, for more details. If the file is found,
1095 the algorithm terminates.
1097 5. At this point we remove the font directory and path separator from
1098 the base name. Now the base name is simply the file to be found,
1099 i.e., `ps-encodings'.
1101 6. Searches for the base name in the path constructed in the first
1102 step. If the file is found, the algorithm terminates.
1104 7. Searches for the base name in the standard configuration path. If
1105 the file is found, the algorithm terminates.
1107 8. The algorithm terminates unsuccessfully.
1109 So, as you see, there are several ways to configure the PostScript
1110 drivers. Careful selection of techniques can make the configuration
1111 very flexible indeed.
1114 File: pspp.info, Node: PS font options, Next: PS line options, Prev: PS file options, Up: PostScript driver class
1116 PostScript font options
1117 -----------------------
1119 The list of available font options is short and sweet:
1121 `prop-font=FONT-NAME'
1122 Sets the default proportional font. The name should be that of a
1123 PostScript font. Default: `"Helvetica"'.
1125 `fixed-font=FONT-NAME'
1126 Sets the default fixed-pitch font. The name should be that of a
1127 PostScript font. Default: `"Courier"'.
1129 `font-size=FONT-SIZE'
1130 Sets the size of the default fonts, in thousandths of a point.
1134 File: pspp.info, Node: PS line options, Next: Prologue, Prev: PS font options, Up: PostScript driver class
1136 PostScript line options
1137 -----------------------
1139 Most tables contain lines, or rules, between cells. Some features of
1140 the way that lines are drawn in PostScript tables are user-definable:
1143 Sets the style used for lines used to divide tables into sections.
1144 STYLE must be either `thick', in which case thick lines are used,
1145 or DOUBLE, in which case double lines are used. Default: `thick'.
1147 `line-gutter=DIMENSION'
1148 Sets the line gutter, which is the amount of whitespace on either
1149 side of lines that border text or graphics objects. *Note
1150 Dimensions::. Default: `0.5pt'.
1152 `line-spacing=DIMENSION'
1153 Sets the line spacing, which is the amount of whitespace that
1154 separates lines that are side by side, as in a double line.
1157 `line-width=DIMENSION'
1158 Sets the width of a typical line used in tables. Default: `0.5pt'.
1160 `line-width-thick=DIMENSION'
1161 Sets the width of a thick line used in tables. Not used if
1162 `line-style' is set to `thick'. Default: `1.5pt'.
1165 File: pspp.info, Node: Prologue, Next: Encodings, Prev: PS line options, Up: PostScript driver class
1167 The PostScript prologue
1168 -----------------------
1170 Most PostScript files that are generated mechanically by programs
1171 consist of two parts: a prologue and a body. The prologue is generally
1172 a collection of boilerplate. Only the body differs greatly between two
1173 outputs from the same program.
1175 This is also the strategy used in the PSPP PostScript driver. In
1176 general, the prologue supplied with PSPP will be more than sufficient.
1177 In this case, you will not need to read the rest of this section.
1178 However, hackers might want to know more. Read on, if you fall into
1181 The prologue is dumped into the output stream essentially unmodified.
1182 However, two actions are performed on its lines. First, certain lines
1183 may be omitted as specified in the prologue file itself. Second,
1184 variables are substituted.
1186 The following lines are omitted:
1188 1. All lines that contain three bangs in a row (`!!!').
1190 2. Lines that contain `!eps', if the PostScript driver is producing
1191 ordinary PostScript output. Otherwise an EPS file is being
1192 produced, and the line is included in the output, although
1193 everything following `!eps' is deleted.
1195 3. Lines that contain `!ps', if the PostScript driver is producing EPS
1196 output. Otherwise, ordinary PostScript is being produced, and the
1197 line is included in the output, although everything following
1200 The following are the variables that are substituted. Only the
1201 variables listed are substituted; environment variables are not. *Note
1202 Environment substitutions::.
1205 The page bounding box, in points, as four space-separated numbers.
1206 For U.S. letter size paper, this is `0 0 612 792'.
1209 PSPP version as a string: `GNU PSPP 0.1b', for example.
1212 Date the file was created. Example: `Tue May 21 13:46:22 1991'.
1215 Value of the `data' PostScript driver option, as one of the strings
1216 `Clean7Bit', `Clean8Bit', or `Binary'.
1219 Page orientation, as one of the strings `Portrait' or `Landscape'.
1222 Under multiuser OSes, the user's login name, taken either from the
1223 environment variable `LOGNAME' or, if that fails, the result of the
1224 C library function `getlogin()'. Defaults to `nobody'.
1227 System hostname as reported by `gethostname()'. Defaults to
1231 Name of the default proportional font, prefixed by the word `font'
1232 and a space. Example: `font Times-Roman'.
1235 Name of the default fixed-pitch font, prefixed by the word `font'
1239 The page scaling factor as a floating-point number. Example:
1240 `1.0'. Note that this is also passed as an argument to the BP
1246 The paper length and paper width, respectively, in thousandths of a
1247 point. Note that these are also passed as arguments to the BP
1253 The left margin and top margin, respectively, in thousandths of a
1254 point. Note that these are also passed as arguments to the BP
1258 Document title as a string. This is not the title specified in the
1259 PSPP syntax file. A typical title is the word `PSPP' followed by
1260 the syntax file name in parentheses. Example: `PSPP (<stdin>)'.
1263 PSPP syntax file name. Example: `mary96/first.stat'.
1265 Any other questions about the PostScript prologue can best be
1266 answered by examining the default prologue or the PSPP source.
1269 File: pspp.info, Node: Encodings, Prev: Prologue, Up: PostScript driver class
1271 PostScript encodings
1272 --------------------
1274 PostScript fonts often contain many more than 256 characters, in
1275 order to accommodate foreign language characters and special symbols.
1276 PostScript uses "encodings" to map these onto single-byte symbol sets.
1277 Each font can have many different encodings applied to it.
1279 PSPP's PostScript driver needs to know which encoding to apply to
1280 each font. It can determine this from the information encapsulated in
1281 the Groff font description that it reads. However, there is an
1282 additional problem--for efficiency, the PostScript driver needs to have
1283 a complete list of all encodings that will be used in the entire
1284 session _when it opens the output file_. For this reason, it can't use
1285 the information built into the fonts because it doesn't know which fonts
1288 As a stopgap solution, there are two mechanisms for specifying which
1289 encodings will be used. The first mechanism is automatic and it is the
1290 only one that most PSPP users will ever need. The second mechanism is
1291 manual, but it is more flexible. Either mechanism or both may be used
1294 The first mechanism is activated by the `auto-encode' driver option
1295 (*note PS file options::). When enabled, `auto-encode' causes the
1296 PostScript driver to include the encodings used by the default
1297 proportional and fixed-pitch fonts (*note PS font options::). Many
1298 PSPP output files will only need these encodings.
1300 The second mechanism is the file specified by the `encoding-file'
1301 option (*note PS file options::). If it exists, this file must consist
1302 of lines in PSPP configuration-file format (*note Configuration
1303 files::). Each line that is not a comment should name a PostScript
1304 encoding to include in the output.
1306 It is not an error if an encoding is included more than once, by
1307 either mechanism. It will appear only once in the output. It is also
1308 not an error if an encoding is included in the output but never used.
1309 It _is_ an error if an encoding is used but not included by one of
1310 these mechanisms. In this case, the built-in PostScript encoding
1311 `ISOLatin1Encoding' is substituted.
1314 File: pspp.info, Node: ASCII driver class, Next: HTML driver class, Prev: PostScript driver class, Up: Configuration
1316 The ASCII driver class
1317 ======================
1319 The ASCII driver class produces output that can be displayed on a
1320 terminal or output to printers. All of its options are highly
1321 configurable. The ASCII driver has class name `ascii'.
1323 The ASCII driver is described in further detail below.
1327 * ASCII output options:: Output file options.
1328 * ASCII page options:: Page size, margins, more.
1329 * ASCII font options:: Box character, bold & italics.