From cc1503032752c3f4bf4a1dce48933cb26066211e Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Thu, 5 Jun 2025 14:47:38 -0700 Subject: [PATCH] work on manual --- rust/doc/src/SUMMARY.md | 8 +- rust/doc/src/invoking/pspp-convert.md | 170 +++++++++ rust/doc/src/invoking/pspp-dump-sav.md | 40 +++ rust/doc/src/invoking/pspp-output.md | 211 ++++++++++++ rust/doc/src/invoking/pspp.md | 460 +++++++++++++++++++++++++ 5 files changed, 888 insertions(+), 1 deletion(-) create mode 100644 rust/doc/src/invoking/pspp-convert.md create mode 100644 rust/doc/src/invoking/pspp-dump-sav.md create mode 100644 rust/doc/src/invoking/pspp-output.md create mode 100644 rust/doc/src/invoking/pspp.md diff --git a/rust/doc/src/SUMMARY.md b/rust/doc/src/SUMMARY.md index 8b82d5498e..277484b8c4 100644 --- a/rust/doc/src/SUMMARY.md +++ b/rust/doc/src/SUMMARY.md @@ -2,7 +2,13 @@ [Introduction](introduction.md) [License](license.md) -[Invoking PSPP](invoking-pspp.md) + +# Invoking PSPP programs + +- [Invoking `pspp`](invoking/pspp.md) +- [Invoking `pspp-convert`](invoking/pspp-convert.md) +- [Invoking `pspp-output`](invoking/pspp-output.md) +- [Invoking `pspp-dump-sav`](invoking/pspp-dump-sav.md) # Language Overview diff --git a/rust/doc/src/invoking/pspp-convert.md b/rust/doc/src/invoking/pspp-convert.md new file mode 100644 index 0000000000..988570eb80 --- /dev/null +++ b/rust/doc/src/invoking/pspp-convert.md @@ -0,0 +1,170 @@ +# Invoking `pspp-convert` + +`pspp-convert` is a command-line utility accompanying PSPP. It reads an +SPSS or SPSS/PC+ system file or SPSS portable file or encrypted SPSS +syntax file INPUT and writes a copy of it to another OUTPUT in a +different format. Synopsis: + +``` +pspp-convert [OPTIONS] INPUT OUTPUT + +pspp-convert --help + +pspp-convert --version +``` + +The format of INPUT is automatically detected, when possible. The +character encoding of old SPSS system files cannot always be guessed +correctly, and SPSS/PC+ system files do not include any indication of +their encoding. Use `-e ENCODING` to specify the encoding in this +case. + +By default, the intended format for OUTPUT is inferred based on its +extension: + +* `csv` + `txt` + Comma-separated value. Each value is formatted according to its + variable's print format. The first line in the file contains + variable names. + +* `sav` + `sys` + SPSS system file. + +* `por` + SPSS portable file. + +* `sps` + SPSS syntax file. (Only encrypted syntax files may be converted to + this format.) + +`pspp-convert` can convert most input formats to most output formats. +Encrypted SPSS file formats are exceptions: if the input file is in an +encrypted format, then the output file will be the same format +(decrypted). To decrypt such a file, specify the encrypted file as +INPUT. The output will be the equivalent plaintext file. Options for +the output format are ignored in this case. + +The password for encrypted files can be specified a few different +ways. If the password is known, use the `-p` option (documented below) +or allow `pspp-convert` to prompt for it. If the password is unknown, +use the `-a` and `-l` options to specify how to search for it, or +`--password-list` to specify a file of passwords to try. + +Use `-O FORMAT` to override the inferred format or to specify the +format for unrecognized extensions. + +`pspp-convert` accepts the following general options: + +* `-O FORMAT` + `--output-format=FORMAT` + Sets the output format, where FORMAT is one of the extensions + listed above, e.g.: `-O csv`. Use `--help` to list the supported + output formats. + +* `-c MAXCASES` + `--cases=MAXCASES` + By default, all cases are copied from INPUT to OUTPUT. Specifying + this option to limit the number of cases written to OUTPUT to + MAXCASES. + +* `-e CHARSET` + `--encoding=CHARSET` + Overrides the encoding in which character strings in INPUT are + interpreted. This option is necessary because old SPSS system + files, and SPSS/PC+ system files, do not self-identify their + encoding. + +* `-k VARIABLE...` + `--keep=VARIABLE...` + By default, `pspp-convert` includes all the variables from the + input file. Use this option to list specific variables to include; + any variables not listed will be dropped. The variables in the + output file will also be reordered into the given order. The + variable list may use `TO` in the same way as in PSPP syntax, e.g. + if the dictionary contains consecutive variables `a`, `b`, `c`, and + `d`, then `--keep='a to d'` will include all of them (and no + others). + +* `-d VARIABLE...` + `--drop=VARIABLE...` + Drops the specified variables from the output. + + When `--keep` and `--drop` are used together, `--keep` is processed + first. + +* `-h`, `--help` + Prints a usage message on stdout and exits. + +* `-v`, `--version` + Prints version information on stdout and exits. + +The following options affect CSV output: + +* `--recode` + By default, `pspp-convert` writes user-missing values to CSV output + files as their regular values. With this option, `pspp-convert` + recodes them to system-missing values (which are written as a + single space). + +* `--no-var-names` + By default, `pspp-convert` writes the variable names as the first + line of output. With this option, `pspp-convert` omits this line. + +* `--labels` + By default, `pspp-convert` writes variables' values to CSV output + files. With this option, `pspp-convert` writes value labels. + +* `--print-formats` + By default, `pspp-convert` writes numeric variables as plain + numbers. This option makes `pspp-convert` honor variables' print + formats. + +* `--decimal=DECIMAL` + This option sets the character used as a decimal point in output. + The default is `.`. + +* `--delimiter=DELIMITER` + This option sets the character used to separate fields in output. + The default is `,`, unless the decimal point is `,`, in which case + `;` is used. + +* `--qualifier=QUALIFIER` + The option sets the character used to quote fields that contain the + delimiter. The default is `"`. + +The following options specify how to obtain the password for +encrypted files: + +* `-p PASSWORD` + `--password=PASSWORD` + Specifies the password to use to decrypt an encrypted SPSS system + file or syntax file. If this option is not specified, + `pspp-convert` will prompt interactively for the password as + necessary. + + > ⚠️ Passwords (and other command-line options) may be visible to + other users on multiuser systems. + + When used with `-a` (or `--password-alphabet`) and `-l` (or + `--password-length`), this option specifies the starting point for + the search. This can be used to restart a search that was + interrupted. + +* `-a ALPHABET` + `--password-alphabet=ALPHABET` + Specifies the alphabet of symbols over which to search for an + encrypted file's password. ALPHABET may include individual + characters and ranges delimited by `-`. For example, `-a a-z` + searches lowercase letters, `-a A-Z0-9` searches uppercase letters + and digits, and `-a ' -~'` searches all printable ASCII characters. + +* `-l MAX-LENGTH` + `--password-length=MAX-LENGTH` + Specifies the maximum length of the passwords to try. + +* `--password-list=FILE` + Specifies a file to read containing a list of passwords to try, one + per line. If FILE is `-`, reads from stdin. + diff --git a/rust/doc/src/invoking/pspp-dump-sav.md b/rust/doc/src/invoking/pspp-dump-sav.md new file mode 100644 index 0000000000..ef409b0481 --- /dev/null +++ b/rust/doc/src/invoking/pspp-dump-sav.md @@ -0,0 +1,40 @@ +# Invoking `pspp-dump-sav` + +`pspp-dump-sav` is a command-line utility accompanying PSPP. It is not +installed by default, so it may be missing from your PSPP installation. +It reads one or more SPSS system files and prints their contents. The +output format is useful for debugging system file readers and writers +and for discovering how to interpret unknown or poorly understood +records. End users may find the output useful for providing the PSPP +developers information about system files that PSPP does not accurately +read. + +Synopsis: + +``` +pspp-dump-sav [-d[MAXCASES] | --data[=MAXCASES]] FILE... + +pspp-dump-sav --help | -h + +pspp-dump-sav --version | -v +``` + +The following options are accepted: + +* `-d[MAXCASES]` + `--data[=MAXCASES]` + By default, `pspp-dump-sav` does not print any of the data in a + system file, only the file headers. Specify this option to print + the data as well. If MAXCASES is specified, then it limits the + number of cases printed. + +* `-h`, `--help` + Prints a usage message on stdout and exits. + +* `-v`, `--version` + Prints version information on stdout and exits. + +Some errors that prevent files from being interpreted successfully +cause `pspp-dump-sav` to exit without reading any additional files +given on the command line. + diff --git a/rust/doc/src/invoking/pspp-output.md b/rust/doc/src/invoking/pspp-output.md new file mode 100644 index 0000000000..c2258e6c69 --- /dev/null +++ b/rust/doc/src/invoking/pspp-output.md @@ -0,0 +1,211 @@ +# Invoking `pspp-output` + +`pspp-output` is a command-line utility accompanying PSPP. It supports +multiple operations on SPSS viewer or `.spv` files, here called SPV +files. SPSS 16 and later writes SPV files to represent the contents of +its output editor. + +SPSS 15 and earlier versions instead use `.spo` files. `pspp-output` +does not support this format. + +`pspp-options` may be invoked in the following ways: + +``` +pspp-output detect FILE + +pspp-output [OPTIONS] dir FILE + +pspp-output [OPTIONS] convert SOURCE DESTINATION + +pspp-output [OPTIONS] get-table-look SOURCE DESTINATION + +pspp-output [OPTIONS] convert-table-look SOURCE DESTINATION + +pspp-output --help + +pspp-output --version +``` + +Each of these forms is documented separately below. `pspp-output` +also has several undocumented command forms that developers may find +useful for debugging. + +## The `detect` Command + +``` +pspp-output detect FILE +``` + +When FILE is an SPV file, `pspp-output` exits successfully without +outputting anything. When FILE is not an SPV file or some other error +occurs, `pspp-output` prints an error message and exits with a failure +indication. + +## The `dir` Command + +``` +pspp-output [OPTIONS] dir FILE +``` + +Prints on stdout a table of contents for SPV file FILE. By default, +this table lists every object in the file, except for hidden objects. +See [Input Selection Options](#input-selection-options), for +information on the options available to select a subset of objects. + +The following additional option for `dir` is intended mainly for use +by PSPP developers: + +* `--member-names` + Also show the names of the Zip members associated with each object. + +## The `convert` Command + +``` +pspp-output [OPTIONS] convert SOURCE DESTINATION +``` + +Reads SPV file SOURCE and converts it to another format, writing the +output to DESTINATION. + +By default, the intended format for DESTINATION is inferred based on +its extension, in the same way that the `pspp` program does for its +output files. See [Invoking `pspp`](pspp.md), for details. + +See [Input Selection Options](#input-selection-options), for +information on the options available to select a subset of objects to +include in the output. The following additional options are accepted: + +* `-O format=FORMAT` + Overrides the format inferred from the output file's extension. Use + `--help` to list the available formats. See [Invoking + `pspp`](pspp.md) for details of the available output formats. + +* `-O OPTION=VALUE` + Sets an option for the output file format. See [Invoking + `pspp`](pspp.md) for details of the available output options. + +* `-F`, `--force` + By default, if the source is corrupt or otherwise cannot be + processed, the destination is not written. With `-F` or `--force`, + the destination is written as best it can, even with errors. + +* `--table-look=FILE` + Reads a table style from FILE and applies it to all of the output + tables. The file should be a TableLook `.stt` or `.tlo` file. + +* `--use-page-setup` + By default, the `convert` command uses the default page setup (for + example, page size and margins) for DESTINATION, or the one + specified with `-O` options, if any. Specify this option to ignore + these sources of page setup in favor of the one embedded in the + SPV, if any. + +## The `get-table-look` Command + +``` +pspp-output [OPTIONS] get-table-look SOURCE DESTINATION +``` + +Reads SPV file SOURCE, applies any [input selection +options](#input-selection-options), picks the first table from the +selected object, extracts the TableLook from that table, and writes it +to DESTINATION (typically with an `.stt` extension) in the TableLook +XML format. + +Use `-` for SOURCE to instead write the default look to DESTINATION. + +The user may use the TableLook file to change the style of tables in +other files, by passing it to the `--table-look` option on the `convert` +command. + +## The `convert-table-look` Command + +``` +pspp-output [OPTIONS] convert-table-look SOURCE DESTINATION +``` + +Reads `.stt` or `.tlo` file SOURCE, and writes it back to DESTINATION +(typically with an `.stt` extension) in the TableLook XML format. This +is useful for converting a TableLook `.tlo` file from SPSS 15 or earlier +into the newer `.stt` format. + +## Input Selection Options + +The `dir` and `convert` commands, by default, operate on all of the +objects in the source SPV file, except for objects that are not visible +in the output viewer window. The user may specify these options to +select a subset of the input objects. When multiple options are used, +only objects that satisfy all of them are selected: + +* `--select=[^]CLASS...` + Include only objects of the given CLASS; with leading `^`, include + only objects not in the class. Use commas to separate multiple + classes. The supported classes are `charts`, `headings`, `logs`, + `models`, `tables`, `texts`, `trees`, `warnings`, `outlineheaders`, + `pagetitle`, `notes`, `unknown`, and `other`. + + Use `--select=help` to print this list of classes. + +* `--commands=[^]COMMAND...` + `--subtypes=[^]SUBTYPE...` + `--labels=[^]LABEL...` + Include only objects with the specified COMMAND, SUBTYPE, or LABEL. + With a leading `^`, include only the objects that do not match. + Multiple values may be specified separated by commas. An asterisk + at the end of a value acts as a wildcard. + + The `--command` option matches command identifiers, case + insensitively. All of the objects produced by a single command use + the same, unique command identifier. Command identifiers are + always in English regardless of the language used for output. They + often differ from the command name in PSPP syntax. Use the + `pspp-output` program's `dir` command to print command identifiers + in particular output. + + The `--subtypes` option matches particular tables within a command, + case insensitively. Subtypes are not necessarily unique: two + commands that produce similar output tables may use the same + subtype. Subtypes are always in English and `dir` will print them. + + The `--labels` option matches the labels in table output (that is, + the table titles). Labels are affected by the output language, + variable names and labels, split file settings, and other factors. + +* `--nth-commands=N...` + Include only objects from the Nth command that matches `--command` + (or the Nth command overall if `--command` is not specified), where + N is 1 for the first command, 2 for the second, and so on. + +* `--instances=INSTANCE...` + Include the specified INSTANCE of an object that matches the other + criteria within a single command. The INSTANCE may be a number (1 + for the first instance, 2 for the second, and so on) or `last` for + the last instance. + +* `--show-hidden` + Include hidden output objects in the output. By default, they are + excluded. + +* `--or` + Separates two sets of selection options. Objects selected by + either set of options are included in the output. + +The following additional input selection options are intended mainly +for use by PSPP developers: + +* `--errors` + Include only objects that cause an error when read. With the + `convert` command, this is most useful in conjunction with the + `--force` option. + +* `--members=MEMBER...` + Include only the objects that include a listed Zip file MEMBER. + More than one name may be included, comma-separated. The members + in an SPV file may be listed with the `dir` command by adding the + `--show-members` option or with the `zipinfo` program included with + many operating systems. Error messages that `pspp-output` prints + when it reads SPV files also often include member names. + +* `--member-names` + Displays the name of the Zip member or members associated with each + object just above the object itself. diff --git a/rust/doc/src/invoking/pspp.md b/rust/doc/src/invoking/pspp.md new file mode 100644 index 0000000000..44d8fc98ca --- /dev/null +++ b/rust/doc/src/invoking/pspp.md @@ -0,0 +1,460 @@ +# Invoking `pspp` + +This chapter describes how to invoke `pspp`, PSPP's main command-line +user 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. + -- 2.30.2