--- /dev/null
+# Invoking `pspp`
+
+PSPP has two separate user interfaces. This chapter describes `pspp`,
+PSPP's command-line driven text-based user interface. The following
+chapter briefly describes PSPPIRE, the graphical user interface to PSPP.
+
+ The sections below describe the `pspp` program's command-line
+interface.
+
+## Main Options
+
+Here is a summary of all the options, grouped by type, followed by
+explanations in the same order.
+
+ In the table, arguments to long options also apply to any
+corresponding short options.
+
+```
+_Non-option arguments_
+ SYNTAX-FILE
+
+_Output options_
+ -o, --output=OUTPUT-FILE
+ -O OPTION=VALUE
+ -O format=FORMAT
+ -O device={terminal|listing}
+ --no-output
+ --table-look=FILE
+ -e, --error-file=ERROR-FILE
+
+_Language options_
+ -I, --include=DIR
+ -I-, --no-include
+ -b, --batch
+ -i, --interactive
+ -r, --no-statrc
+ -a, --algorithm={compatible|enhanced}
+ -x, --syntax={compatible|enhanced}
+ --syntax-encoding=ENCODING
+
+_Informational options_
+ -h, --help
+ -V, --version
+
+_Other options_
+ -s, --safer
+ --testing-mode
+```
+
+* `SYNTAX-FILE`
+ Read and execute the named syntax file. If no syntax files are
+ specified, PSPP prompts for commands. If any syntax files are
+ specified, PSPP by default exits after it runs them, but you may
+ make it prompt for commands by specifying `-` as an additional
+ syntax file.
+
+* `-o OUTPUT-FILE`
+ Write output to OUTPUT-FILE. PSPP has several different output
+ drivers that support output in various formats (use `--help` to
+ list the available formats). Specify this option more than once to
+ produce multiple output files, presumably in different formats.
+
+ Use `-` as OUTPUT-FILE to write output to standard output.
+
+ If no `-o` option is used, then PSPP writes text and CSV output to
+ standard output and other kinds of output to whose name is based on
+ the format, e.g. `pspp.pdf` for PDF output.
+
+* `-O OPTION=VALUE`
+ Sets an option for the output file configured by a preceding `-o`.
+ Most options are specific to particular output formats. A few
+ options that apply generically are listed below.
+
+* `-O format=FORMAT`
+ PSPP uses the extension of the file name given on `-o` to select an
+ output format. Use this option to override this choice by
+ specifying an alternate format, e.g. `-o pspp.out -O format=html`
+ to write HTML to a file named `pspp.out`. Use `--help` to list the
+ available formats.
+
+* `-O device={terminal|listing}`
+ Sets whether PSPP considers the output device configured by the
+ preceding `-o` to be a terminal or a listing device. This affects
+ what output will be sent to the device, as configured by the
+ [`SET`](commands/utilities/set.md) command's output routing
+ subcommands. By default, output written to standard output is
+ considered a terminal device and other output is considered a
+ listing device.
+
+* `--no-output`
+ Disables output entirely, if neither `-o` nor `-O` is also used.
+ If one of those options is used, `--no-output` has no effect.
+
+* `--table-look=FILE`
+ Reads a table style from FILE and applies it to all PSPP table
+ output. The file should be a TableLook `.stt` or `.tlo` file.
+ PSPP searches for FILE in the current directory, then in
+ `.pspp/looks` in the user's home directory, then in a `looks`
+ subdirectory inside PSPP's data directory (usually
+ `/usr/local/share/pspp`). If PSPP cannot find FILE under the given
+ name, it also tries adding a `.stt` extension.
+
+ When this option is not specified, PSPP looks for `default.stt`
+ using the algorithm above, and otherwise it falls back to a default
+ built-in style.
+
+ Using [`SET TLOOK`](commands/utilities/set.md#tlook) in PSPP syntax
+ overrides the style set on the command line.
+
+* `-e ERROR-FILE`
+ `--error-file=ERROR-FILE`
+ Configures a file to receive PSPP error, warning, and note messages
+ in plain text format. Use `-` as ERROR-FILE to write messages to
+ standard output. The default error file is standard output in the
+ absence of these options, but this is suppressed if an output
+ device writes to standard output (or another terminal), to avoid
+ printing every message twice. Use `none` as ERROR-FILE to
+ explicitly suppress the default.
+
+* `-I DIR`
+ `--include=DIR`
+ Appends DIR to the set of directories searched by the
+ [`INCLUDE`](commands/utilities/include.md) and
+ [`INSERT`](commands/utilities/insert.md) commands.
+
+* `-I-`, `--no-include`
+ Clears all directories from the include path, including directories
+ inserted in the include path by default. The default include path
+ is `.` (the current directory), followed by `.pspp` in the user's
+ home directory, followed by PSPP's system configuration directory
+ (usually `/etc/pspp` or `/usr/local/etc/pspp`).
+
+* `-b`, `--batch`
+ `-i`, `--interactive`
+ These options forces syntax files to be interpreted in batch mode or
+ interactive mode, respectively, rather than the default "auto" mode.
+ See [Syntax Variants](language/basics/syntax-variants.md), for a
+ description of the differences.
+
+* `-r`, `--no-statrc`
+ By default, at startup PSPP searches for a file named `rc` in the
+ include path (described above) and, if it finds one, runs the
+ commands in it. This option disables this behavior.
+
+* `-a {enhanced|compatible}`
+ `--algorithm={enhanced|compatible}`
+ With `enhanced`, the default, PSPP uses the best implemented
+ algorithms for statistical procedures. With `compatible`, however,
+ PSPP will in some cases use inferior algorithms to produce the same
+ results as the proprietary program SPSS.
+
+ Some commands have subcommands that override this setting on a per
+ command basis.
+
+* `-x {enhanced|compatible}`
+ `--syntax={enhanced|compatible}`
+ With `enhanced`, the default, PSPP accepts its own extensions
+ beyond those compatible with the proprietary program SPSS. With
+ `compatible`, PSPP rejects syntax that uses these extensions.
+
+* `--syntax-encoding=ENCODING`
+ Specifies ENCODING as the encoding for syntax files named on the
+ command line. The ENCODING also becomes the default encoding for
+ other syntax files read during the PSPP session by the
+ [`INCLUDE`](commands/utilities/include.md) and
+ [`INSERT`](commands/utilities/insert.md) commands. See
+ [`INSERT`](commands/utilities/insert.md) for the accepted forms of
+ ENCODING.
+
+* `--help`
+ Prints a message describing PSPP command-line syntax and the
+ available device formats, then exits.
+
+* `-V`, `--version`
+ Prints a brief message listing PSPP's version, warranties you don't
+ have, copying conditions and copyright, and e-mail address for bug
+ reports, then exits.
+
+* `-s`, `--safer`
+ Disables certain unsafe operations. This includes the `ERASE` and
+ `HOST` commands, as well as use of pipes as input and output files.
+
+* `--testing-mode`
+ Invoke heuristics to assist with testing PSPP. For use by `make
+ check` and similar scripts.
+
+## PDF, PostScript, SVG, and PNG Output Options
+
+To produce output in PDF, PostScript, SVG, or PNG format, specify `-o
+FILE` on the PSPP command line, optionally followed by any of the
+options shown in the table below to customize the output format.
+
+PDF, PostScript, and SVG use real units: each dimension among the
+options listed below may have a suffix `mm` for millimeters, `in` for
+inches, or `pt` for points. Lacking a suffix, numbers below 50 are
+assumed to be in inches and those above 50 are assumed to be in
+millimeters.
+
+PNG files are pixel-based, so dimensions in PNG output must
+ultimately be measured in pixels. For output to these files, PSPP
+translates the specified dimensions to pixels at 72 pixels per inch.
+For PNG output only, fonts are by default rendered larger than this, at
+96 pixels per inch.
+
+An SVG or PNG file can only hold a single page. When PSPP outputs
+more than one page to SVG or PNG, it creates multiple files. It outputs
+the second page to a file named with a `-2` suffix, the third with a
+`-3` suffix, and so on.
+
+* `-O format={pdf|ps|svg|png}`
+ Specify the output format. This is only necessary if the file name
+ given on `-o` does not end in `.pdf`, `.ps`, `.svg`, or `.png`.
+
+* `-O paper-size=PAPER-SIZE`
+ Paper size, as a name (e.g. `a4`, `letter`) or measurements (e.g.
+ `210x297`, `8.5x11in`).
+
+ The default paper size is taken from the `PAPERSIZE` environment
+ variable or the file indicated by the `PAPERCONF` environment
+ variable, if either variable is set. If not, and your system
+ supports the `LC_PAPER` locale category, then the default paper
+ size is taken from the locale. Otherwise, if `/etc/papersize`
+ exists, the default paper size is read from it. As a last resort,
+ A4 paper is assumed.
+
+* `-O foreground-color=COLOR`
+ Sets COLOR as the default color for lines and text. Use a CSS
+ color format (e.g. `#RRGGBB`) or name (e.g. `black`) as COLOR.
+
+* `-O orientation=ORIENTATION`
+ Either `portrait` or `landscape`. Default: `portrait`.
+
+* `-O left-margin=DIMENSION`
+ `-O right-margin=DIMENSION`
+ `-O top-margin=DIMENSION`
+ `-O bottom-margin=DIMENSION`
+ Sets the margins around the page. See below for the allowed forms
+ of DIMENSION. Default: `0.5in`.
+
+* `-O object-spacing=DIMENSION`
+ Sets the amount of vertical space between objects (such as headings
+ or tables).
+
+* `-O prop-font=FONT-NAME`
+ Sets the default font used for ordinary text. Most systems support
+ CSS-like font names such as "Sans Serif", but a wide range of
+ system-specific fonts are likely to be supported as well.
+
+ Default: proportional font `Sans Serif`.
+
+* `-O font-size=FONT-SIZE`
+ Sets the size of the default fonts, in thousandths of a point.
+ Default: 10000 (10 point).
+
+* `-O trim=true`
+ This option makes PSPP trim empty space around each page of output,
+ before adding the margins. This can make the output easier to
+ include in other documents.
+
+* `-O outline=BOOLEAN`
+ For PDF output only, this option controls whether PSPP includes an
+ outline in the output file. PDF viewers usually display the
+ outline as a side bar that allows for easy navigation of the file.
+ The default is true unless `-O trim=true` is also specified. (The
+ Cairo graphics library that PSPP uses to produce PDF output has a
+ bug that can cause a crash when outlines and trimming are used
+ together.)
+
+* `-O font-resolution=DPI`
+ Sets the resolution for font rendering, in dots per inch. For PDF,
+ PostScript, and SVG output, the default is 72 dpi, so that a
+ 10-point font is rendered with a height of 10 points. For PNG
+ output, the default is 96 dpi, so that a 10-point font is rendered
+ with a height of 10 / 72 * 96 = 13.3 pixels. Use a larger DPI to
+ enlarge text output, or a smaller DPI to shrink it.
+
+## Plain Text Output Options
+
+PSPP can produce plain text output, drawing boxes using ASCII or Unicode
+line drawing characters. To produce plain text output, specify `-o
+FILE` on the PSPP command line, optionally followed by options from the
+table below to customize the output format.
+
+Plain text output is encoded in UTF-8.
+
+* `-O format=txt`
+ Specify the output format. This is only necessary if the file name
+ given on `-o` does not end in `.txt` or `.list`.
+
+* `-O charts={TEMPLATE.png|none}`
+ Name for chart files included in output. The value should be a
+ file name that includes a single `#` and ends in `png`. When a
+ chart is output, the `#` is replaced by the chart number. The
+ default is the file name specified on `-o` with the extension
+ stripped off and replaced by `-#.png`.
+
+ Specify `none` to disable chart output.
+
+* `-O foreground-color=COLOR`
+ `-O background-color=COLOR`
+ Sets COLOR as the color to be used for the background or foreground
+ to be used for charts. Color should be given in the format
+ `#RRRRGGGGBBBB`, where RRRR, GGGG and BBBB are 4 character
+ hexadecimal representations of the red, green and blue components
+ respectively. If charts are disabled, this option has no effect.
+
+* `-O width=COLUMNS`
+ Width of a page, in columns. If unspecified or given as `auto`, the
+ default is the width of the terminal, for interactive output, or the
+ [`WIDTH`](commands/utilities/set.md#width) setting, for output to a
+ file.
+
+* `-O box={ascii|unicode}`
+ Sets the characters used for lines in tables. If set to `ascii`,
+ output uses use the characters `-`, `|`, and `+` for single-width
+ lines and `=` and `#` for double-width lines. If set to `unicode`
+ then, output uses Unicode box drawing characters. The default is
+ `unicode` if the locale's character encoding is "UTF-8" or `ascii`
+ otherwise.
+
+* `-O emphasis={none|bold|underline}`
+ How to emphasize text. Bold and underline emphasis are achieved
+ with overstriking, which may not be supported by all the software
+ to which you might pass the output. Default: `none`.
+
+## SPV Output Options
+
+SPSS 16 and later write `.spv` files to represent the contents of its
+output editor. To produce output in `.spv` format, specify `-o FILE` on
+the PSPP command line, optionally followed by any of the options shown
+in the table below to customize the output format.
+
+* `-O format=spv`
+ Specify the output format. This is only necessary if the file name
+ given on `-o` does not end in `.spv`.
+
+* `-O paper-size=PAPER-SIZE`
+ `-O left-margin=DIMENSION`
+ `-O right-margin=DIMENSION`
+ `-O top-margin=DIMENSION`
+ `-O bottom-margin=DIMENSION`
+ `-O object-spacing=DIMENSION`
+ These have the same syntax and meaning as for [PDF
+ output](#pdf-postscript-svg-and-png-output-options).
+
+## TeX Output Options
+
+If you want to publish statistical results in professional or academic
+journals, you will probably want to provide results in TeX format. To
+do this, specify `-o FILE` on the PSPP command line where FILE is a file
+name ending in `.tex`, or you can specify `-O format=tex`.
+
+The resulting file can be directly processed using TeX or you can
+manually edit the file to add commentary text. Alternatively, you can
+cut and paste desired sections to another TeX file.
+
+## HTML Output Options
+
+To produce output in HTML format, specify `-o FILE` on the PSPP command
+line, optionally followed by any of the options shown in the table below
+to customize the output format.
+
+* `-O format=html`
+ Specify the output format. This is only necessary if the file name
+ given on `-o` does not end in `.html`.
+
+* `-O charts={TEMPLATE.png|none}`
+ Sets the name used for chart files. See [Plain Text Output
+ Options](#plain-text-output-options), for details.
+
+* `-O borders=BOOLEAN`
+ Decorate the tables with borders. If set to false, the tables
+ produced will have no borders. The default value is true.
+
+* `-O bare=BOOLEAN`
+ The HTML output driver ordinarily outputs a complete HTML document.
+ If set to true, the driver instead outputs only what would normally
+ be the contents of the `body` element. The default value is false.
+
+* `-O css=BOOLEAN`
+ Use cascading style sheets. Cascading style sheets give an
+ improved appearance and can be used to produce pages which fit a
+ certain web site's style. The default value is true.
+
+## OpenDocument Output Options
+
+To produce output as an OpenDocument text (ODT) document, specify `-o
+FILE` on the PSPP command line. If FILE does not end in `.odt`, you
+must also specify `-O format=odt`.
+
+ODT support is only available if your installation of PSPP was
+compiled with the libxml2 library.
+
+The OpenDocument output format does not have any configurable
+options.
+
+## Comma-Separated Value Output Options
+
+To produce output in comma-separated value (CSV) format, specify `-o
+FILE` on the PSPP command line, optionally followed by any of the
+options shown in the table below to customize the output format.
+
+* `-O format=csv`
+ Specify the output format. This is only necessary if the file name
+ given on `-o` does not end in `.csv`.
+
+* `-O separator=FIELD-SEPARATOR`
+ Sets the character used to separate fields. Default: a comma
+ (`,`).
+
+* `-O quote=QUALIFIER`
+ Sets QUALIFIER as the character used to quote fields that contain
+ white space, the separator (or any of the characters in the
+ separator, if it contains more than one character), or the quote
+ character itself. If QUALIFIER is longer than one character, only
+ the first character is used; if QUALIFIER is the empty string, then
+ fields are never quoted.
+
+* `-O titles=BOOLEAN`
+ Whether table titles (brief descriptions) should be printed.
+ Default: `on`.
+
+* `-O captions=BOOLEAN`
+ Whether table captions (more extensive descriptions) should be
+ printed. Default: on.
+
+ The CSV format used is an extension to that specified in RFC 4180:
+
+* Tables
+ Each table row is output on a separate line, and each column is
+ output as a field. The contents of a cell that spans multiple rows
+ or columns is output only for the top-left row and column; the rest
+ are output as empty fields.
+
+* Titles
+ When a table has a title and titles are enabled, the title is
+ output just above the table as a single field prefixed by `Table:`.
+
+* Captions
+ When a table has a caption and captions are enabled, the caption is
+ output just below the table as a single field prefixed by
+ `Caption:`.
+
+* Footnotes
+ Within a table, footnote markers are output as bracketed letters
+ following the cell's contents, e.g. `[a]`, `[b]`, ... The
+ footnotes themselves are output following the body of the table, as
+ a separate two-column table introduced with a line that says
+ `Footnotes:`. Each row in the table represent one footnote: the
+ first column is the marker, the second column is the text.
+
+* Text
+ Text in output is printed as a field on a line by itself. The
+ TITLE and SUBTITLE produce similar output, prefixed by `Title:` or
+ `Subtitle:`, respectively.
+
+* Messages
+ Errors, warnings, and notes are printed the same way as text.
+
+* Charts
+ Charts are not included in CSV output.
+
+Successive output items are separated by a blank line.
+
projects / pspp / commitdiff