-@node Invocation
-
-@chapter Starting PSPP
+@node Invoking PSPP
+@chapter Invoking @command{pspp}
@cindex invocation
-@cindex PSPP, invoking
-
-There are two separate user interfaces for PSPP.
-There is the command line interface, which responds to commands
-typed by the user.
-The command line interface is generally available on more platforms
-than the graphic user interface and since it doesn't require a
-graphics device it can be used from a remote terminal.
-Platforms which have a windowing system may also be able to support
-the graphic user interface.
-The graphic user interface can perform all functionality of the
-command line interface.
-In addition it gives an instantaneous view of the data, variables and
-statistical output.
+@cindex @pspp{}, invoking
-Whichever interface you choose, a basic understanding of the concepts
-used by PSPP is necessary before effective use of the system can be achieved.
+@pspp{} has two separate user interfaces. This chapter describes
+@command{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 @command{pspp} program's command-line
+interface.
@menu
-* The command line user interface::
-* The graphic user interface::
+* Main Options::
+* PDF PostScript and SVG Output Options::
+* Plain Text Output Options::
+* HTML Output Options::
+* OpenDocument Output Options::
+* Comma-Separated Value Output Options::
@end menu
+@node Main Options
+@section Main Options
-@node The command line user interface
-@section The command line user interface
+Here is a summary of all the options, grouped by type, followed by
+explanations in the same order.
-@cindex command line, options
-@cindex options, command-line
+In the table, arguments to long options also apply to any
+corresponding short options.
+@table @emph
+@item Non-option arguments
@example
-pspp [ -B @var{dir} | --config-dir=@var{dir} ] [ -o @var{device} | --device=@var{device} ]
- [ -a @{compatible|enhanced@} | --algorithm=@{compatible|enhanced@}]
- [ -x @{compatible|enhanced@} | --syntax=@{compatible|enhanced@}]
- [ -I- | --no-include ]
- [ -I @var{dir} | --include=@var{dir} ] [ -i | --interactive ]
- [ -r | --no-statrc ] [ -h | --help ] [ -l | --list ]
- [ -s | --safer ]
- [ --testing-mode ] [ -V | --version ]
- [ @var{key}=@var{value} ] @var{file}@enddots{}
+@var{syntax-file}
@end example
-@menu
-* Non-option Arguments:: Specifying syntax files and output devices.
-* Configuration Options:: Change the configuration for the current run.
-* Input and output options:: Controlling input and output files.
-* Language control options:: Language variants.
-* Informational options:: Helpful information about PSPP.
-@end menu
-
-@node Non-option Arguments
-@subsection Non-option Arguments
-
-Syntax files and output device substitutions can be specified on
-PSPP's command line:
-
-@table @code
-@item @var{file}
-
-A file by itself on the command line will be executed as a syntax file.
-If multiple files are specified, they are executed in order, as if
-their contents had been given in a single file.
-PSPP terminates after the syntax files run, unless the @code{-i} or
-@code{--interactive} option is given (@pxref{Language control options}).
-
-@item @var{key}=@var{value}
-
-Defines an output device macro @var{key} to expand to @var{value},
-overriding any macro having the same @var{key} defined in the device
-configuration file. @xref{Macro definitions}.
-
-@end table
-
-There is one other way to specify a syntax file, if your operating
-system supports it. If you have a syntax file @file{foobar.stat}, put
-the notation
-
+@item Output options
@example
-#! /usr/local/bin/pspp
+-o, --output=@var{output-file}
+-O @var{option}=@var{value}
+-O format=@var{format}
+-O device=@{terminal|listing@}
+--no-output
+-e, --error-file=@var{error-file}
@end example
-at the top, and mark the file as executable with @code{chmod +x
-foobar.stat}. (If PSPP is not installed in @file{/usr/local/bin},
-then insert its actual installation directory into the syntax file
-instead.) Now you should be able to invoke the syntax file just by
-typing its name. You can include any options on the command line as
-usual. PSPP entirely ignores any lines beginning with @samp{#!}.
-
-@node Configuration Options
-@subsection Configuration Options
-
-Configuration options are used to change PSPP's configuration for the
-current run. The configuration options are:
-
-@table @code
-@item -a @{compatible|enhanced@}
-@itemx --algorithm=@{compatible|enhanced@}
-
-If you chose @code{compatible}, then PSPP will use the same algorithms
-as used by some proprietary statistical analysis packages.
-This is not recommended, as these algorithms are inferior and in some cases
-compeletely broken.
-The default setting is @code{enhanced}.
-Certain commands have subcommands which allow you to override this setting on
-a per command basis.
-
-@item -B @var{dir}
-@itemx --config-dir=@var{dir}
-
-Sets the configuration directory to @var{dir}. @xref{File locations}.
+@item Language options
+@example
+-I, --include=@var{dir}
+-I-, --no-include
+-b, --batch
+-i, --interactive
+-r, --no-statrc
+-a, --algorithm=@{compatible|enhanced@}
+-x, --syntax=@{compatible|enhanced@}
+--syntax-encoding=@var{encoding}
+@end example
-@item -o @var{device}
-@itemx --device=@var{device}
+@item Informational options
+@example
+-h, --help
+-V, --version
+@end example
-Selects the output device with name @var{device}. If this option is
-given more than once, then all devices mentioned are selected. This
-option disables all devices besides those mentioned on the command line.
+@item Other options
+@example
+-s, --safer
+--testing-mode
+@end example
@end table
-@node Input and output options
-@subsection Input and output options
-
-Input and output options affect how PSPP reads input and writes
-output. These are the input and output options:
-
-@table @code
-@item -I-
-@itemx --no-include
-
-Clears all directories from the include path. This includes all
-directories put in the include path by default. @xref{Miscellaneous
-configuring}.
+@table @asis
+@item @var{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 @samp{-} as an additional syntax
+file.
+
+@item @option{-o @var{output-file}}
+Write output to @var{output-file}. @pspp{} has several different output
+drivers that support output in various formats (use @option{--help} to
+list the available formats). Specify this option more than once to
+produce multiple output files, presumably in different formats.
+
+Use @samp{-} as @var{output-file} to write output to standard output.
+
+If no @option{-o} option is used, then @pspp{} writes output to standard
+output in plain text format.
+
+@item @option{-O @var{option}=@var{value}}
+Sets an option for the output file configured by a preceding
+@option{-o}. Most options are specific to particular output formats.
+A few options that apply generically are listed below.
+
+@item @option{-O format=@var{format}}
+@pspp{} uses the extension of the file name given on @option{-o} to
+select an output format. Use this option to override this choice by
+specifying an alternate format, e.g.@: @option{-o pspp.out -O html} to
+write HTML to a file named @file{pspp.out}. Use @option{--help} to
+list the available formats.
+
+@item @option{-O device=@{terminal|listing@}}
+Sets whether @pspp{} considers the output device configured by the
+preceding @option{-o} to be a terminal or a listing device. This
+affects what output will be sent to the device, as configured by the
+SET command's output routing subcommands (@pxref{SET}). By default,
+output written to standard output is considered a terminal device and
+other output is considered a listing device.
+
+@item @option{--no-output}
+Disables output entirely, if neither @option{-o} nor @option{-O} is
+also used. If one of those options is used, @option{--no-output} has
+no effect.
+
+@item @option{-e @var{error-file}}
+@itemx @option{--error-file=@var{error-file}}
+Configures a file to receive @pspp{} error, warning, and note messages in
+plain text format. Use @samp{-} as @var{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 @samp{none} as @var{error-file} to
+explicitly suppress the default.
+
+@item @option{-I @var{dir}}
+@itemx @option{--include=@var{dir}}
+Appends @var{dir} to the set of directories searched by the @cmd{INCLUDE}
+(@pxref{INCLUDE}) and @cmd{INSERT} (@pxref{INSERT}) commands.
+
+@item @option{-I-}
+@itemx @option{--no-include}
+Clears all directories from the include path, including directories
+inserted in the include path by default. The default include path is
+@file{.} (the current directory), followed by @file{.pspp} in the
+user's home directory, followed by @pspp{}'s system configuration
+directory (usually @file{/etc/pspp} or @file{/usr/local/etc/pspp}).
+
+@item @option{-b}
+@item @option{--batch}
+@item @option{-i}
+@itemx @option{--interactive}
+These options forces syntax files to be interpreted in batch mode or
+interactive mode, respectively, rather than the default ``auto'' mode.
+@xref{Syntax Variants}, for a description of the differences.
+
+@item @option{-r}
+@itemx @option{--no-statrc}
+Disables running @file{rc} at @pspp{} startup time.
+
+@item @option{-a @{enhanced|compatible@}}
+@itemx @option{--algorithm=@{enhanced|compatible@}}
+With @code{enhanced}, the default, @pspp{} uses the best implemented
+algorithms for statistical procedures. With @code{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.
+
+@item @option{-x @{enhanced|compatible@}}
+@itemx @option{--syntax=@{enhanced|compatible@}}
+With @code{enhanced}, the default, @pspp{} accepts its own extensions
+beyond those compatible with the proprietary program SPSS. With
+@code{compatible}, @pspp{} rejects syntax that uses these extensions.
+
+@item @option{--syntax-encoding=@var{encoding}}
+Specifies @var{encoding} as the encoding for syntax files named on the
+command line. The @var{encoding} also becomes the default encoding
+for other syntax files read during the @pspp{} session by the
+@cmd{INCLUDE} and @cmd{INSERT} commands. @xref{INSERT}, for the
+accepted forms of @var{encoding}.
+
+@item @option{--help}
+Prints a message describing @pspp{} command-line syntax and the available
+device formats, then exits.
+
+@item @option{-V}
+@itemx @option{--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.
-@item -I @var{dir}
-@itemx --include=@var{dir}
+@item @option{-s}
+@itemx @option{--safer}
+Disables certain unsafe operations. This includes the @subcmd{ERASE} and
+@subcmd{HOST} commands, as well as use of pipes as input and output files.
-Appends directory @var{dir} to the path that is searched for include
-files in PSPP syntax files.
+@item @option{--testing-mode}
+Invoke heuristics to assist with testing @pspp{}. For use
+by @command{make check} and similar scripts.
+@end table
-@item --testing-mode
+@node PDF PostScript and SVG Output Options
+@section PDF, PostScript, and SVG Output Options
+@cindex PDF
+@cindex Postscript
+@cindex SVG
+
+To produce output in PDF, PostScript, and SVG formats, specify
+@option{-o @var{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 output is only available if your installation
+of @pspp{} was compiled with the Cairo library.
+
+@table @asis
+@item @option{-O format=@{pdf|ps|svg@}}
+Specify the output format. This is only necessary if the file name
+given on @option{-o} does not end in @file{.pdf}, @file{.ps}, or
+@file{.svg}.
+
+@item @option{-O paper-size=@var{paper-size}}
+Paper size, as a name (e.g.@: @code{a4}, @code{letter}) or
+measurements (e.g.@: @code{210x297}, @code{8.5x11in}).
+
+The default paper size is taken from the @env{PAPERSIZE} environment
+variable or the file indicated by the @env{PAPERCONF} environment
+variable, if either variable is set. If not, and your system supports
+the @code{LC_PAPER} locale category, then the default paper size is
+taken from the locale. Otherwise, if @file{/etc/papersize} exists,
+the default paper size is read from it. As a last resort, A4 paper is
+assumed.
+
+@item @option{-O foreground-color=@var{color}}
+@itemx @option{-O background-color=@var{color}}
+Sets @var{color} as the color to be used for the background or foreground.
+Color should be given in the format @code{#@var{RRRR}@var{GGGG}@var{BBBB}},
+where @var{RRRR}, @var{GGGG} and @var{BBBB} are 4 character hexadecimal
+representations of the red, green and blue components respectively.
+
+@item @option{-O orientation=@var{orientation}}
+Either @code{portrait} or @code{landscape}. Default: @code{portrait}.
+
+@item @option{-O left-margin=@var{dimension}}
+@itemx @option{-O right-margin=@var{dimension}}
+@itemx @option{-O top-margin=@var{dimension}}
+@itemx @option{-O bottom-margin=@var{dimension}}
+Sets the margins around the page. See
+below for the allowed forms of @var{dimension} Default: @code{0.5in}.
+
+@item @option{-O prop-font=@var{font-name}}
+@itemx @option{-O emph-font=@var{font-name}}
+@itemx @option{-O fixed-font=@var{font-name}}
+Sets the font used for proportional, emphasized, or fixed-pitch text.
+Most systems support CSS-like font names such as ``serif'' and
+``monospace'', but a wide range of system-specific font are likely to
+be supported as well.
+
+Default: proportional font @code{serif}, emphasis font @code{serif
+italic}, fixed-pitch font @code{monospace}.
+
+@item @option{-O font-size=@var{font-size}}
+Sets the size of the default fonts, in thousandths of a point. Default:
+10000 (10 point).
+
+@item @option{-O line-gutter=@var{dimension}}
+Sets the width of white space on either side of lines that border text
+or graphics objects. Default: @code{1pt}.
+
+@item @option{-O line-spacing=@var{dimension}}
+Sets the spacing between the lines in a double line in a table.
+Default: @code{1pt}.
+
+@item @option{-O line-width=@var{dimension}}
+Sets the width of the lines used in tables. Default: @code{0.5pt}.
+@end table
-Invoke heuristics to assist with testing PSPP. For use by @code{make
-check} and similar scripts.
+Each @var{dimension} value above may be specified in various units
+based on its suffix: @samp{mm} for millimeters, @samp{in} for inches,
+or @samp{pt} for points. Lacking a suffix, numbers below 50 are
+assumed to be in inches and those about 50 are assumed to be in
+millimeters.
+
+@node Plain Text Output Options
+@section 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 @option{-o @var{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.
+
+@table @asis
+@item @option{-O format=txt}
+Specify the output format. This is only necessary if the file name
+given on @option{-o} does not end in @file{.txt} or @file{.list}.
+
+@item @option{-O charts=@{@var{template}.png|none@}}
+Name for chart files included in output. The value should be a file
+name that includes a single @samp{#} and ends in @file{png}. When a
+chart is output, the @samp{#} is replaced by the chart number. The
+default is the file name specified on @option{-o} with the extension
+stripped off and replaced by @file{-#.png}.
+
+Specify @code{none} to disable chart output. Charts are always
+disabled if your installation of @pspp{} was compiled without the
+Cairo library.
+
+@item @option{-O paginate=@var{boolean}}
+If set, @pspp{} writes an ASCII formfeed the end of every page. Default:
+@code{off}.
+
+@item @option{-O headers=@var{boolean}}
+If enabled, @pspp{} prints two lines of header information giving title
+and subtitle, page number, date and time, and @pspp{} version are printed
+at the top of every page. These two lines are in addition to any top
+margin requested. Default: @code{off}.
+
+@item @option{-O length=@var{line-count}}
+Physical length of a page. Headers and margins are subtracted from
+this value. You may specify the number of lines as a number, or for
+screen output you may specify @code{auto} to track the height of the
+terminal as it changes. Default: @code{66}.
+
+@item @option{-O width=@var{character-count}}
+Width of a page, in characters. Margins are subtracted from this
+value. For screen output you may specify @code{auto} in place of a
+number to track the width of the terminal as it changes. Default:
+@code{79}.
+
+@item @option{-O top-margin=@var{top-margin-lines}}
+Length of the top margin, in lines. @pspp{} subtracts this value from
+the page length. Default: @code{0}.
+
+@item @option{-O bottom-margin=@var{bottom-margin-lines}}
+Length of the bottom margin, in lines. @pspp{} subtracts this value from
+the page length. Default: @code{0}.
+
+@item @option{-O box=@{ascii|unicode@}}
+Sets the characters used for lines in tables. The default,
+@code{ascii}, uses @samp{-}, @samp{|}, and @samp{+} for single-width
+lines and @samp{=} and @samp{#} for double-width lines. Specify
+@code{unicode} to use Unicode box drawing characters.
+
+@item @option{-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: @code{none}.
@end table
-@node Language control options
-@subsection Language control options
+@node HTML Output Options
+@section HTML Output Options
+@cindex HTML
+To produce output in HTML format, specify @option{-o @var{file}} on
+the @pspp{} command line, optionally followed by any of the options shown
+in the table below to customize the output format.
-Language control options control how PSPP syntax files are parsed and
-interpreted. The available language control options are:
+@table @asis
+@item @option{-O format=html}
+Specify the output format. This is only necessary if the file name
+given on @option{-o} does not end in @file{.html}.
-@table @code
-@item -i
-@itemx --interactive
+@item @option{-O charts=@{@var{template}.png|none@}}
+Sets the name used for chart files. @xref{Plain Text Output Options},
+for details.
-When a syntax file is specified on the command line, PSPP normally
-terminates after processing it. Giving this option will cause PSPP to
-bring up a command prompt after processing the syntax file.
+@item @option{-O borders=@var{boolean}}
+Decorate the tables with borders. If set to false, the tables produced
+will have no borders. The default value is true.
-In addition, this forces syntax files to be interpreted in interactive
-mode, rather than the default batch mode. @xref{Tokenizing lines}, for
-information on the differences between batch mode and interactive mode
-command interpretation.
+@item @option{-O css=@var{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.
-@item -r
-@itemx --no-statrc
+@end table
-Prevents the execution of the PSPP startup syntax file.
+@node OpenDocument Output Options
+@section OpenDocument Output Options
-@item -s
-@itemx --safer
+To produce output as an OpenDocument text (ODT) document, specify
+@option{-o @var{file}} on the @pspp{} command line. If @var{file} does
+not end in @file{.odt}, you must also specify @option{-O format=odt}.
-Disables certain unsafe operations. This includes the ERASE and
-HOST commands, as well as use of pipes as input and output files.
-@end table
+ODT support is only available if your installation of @pspp{} was
+compiled with the libxml2 library.
-@node Informational options
-@subsection Informational options
+The OpenDocument output format does not have any configurable options.
-Informational options cause information about PSPP to be written to
-the terminal. Here are the available options:
+@node Comma-Separated Value Output Options
+@section Comma-Separated Value Output Options
-@table @code
-@item -h
-@item --help
+To produce output in comma-separated value (CSV) format, specify
+@option{-o @var{file}} on the @pspp{} command line, optionally followed
+by any of the options shown in the table below to customize the output
+format.
-Prints a message describing PSPP command-line syntax and the available
-device driver classes, then terminates.
+@table @asis
+@item @option{-O format=csv}
+Specify the output format. This is only necessary if the file name
+given on @option{-o} does not end in @file{.csv}.
-@item -l
-@item --list
+@item @option{-O separator=@var{field-separator}}
+Sets the character used to separate fields. Default: a comma
+(@samp{,}).
-Lists the available device driver classes, then terminates.
+@item @option{-O quote=@var{qualifier}}
+Sets @var{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 @var{qualifier} is longer than one character,
+only the first character is used; if @var{qualifier} is the empty
+string, then fields are never quoted.
-@item -x @{compatible|enhanced@}
-@itemx --syntax=@{compatible|enhanced@}
+@item @option{-O captions=@var{boolean}}
+Whether table captions should be printed. Default: @code{on}.
+@end table
-If you chose @code{compatible}, then PSPP will only accept command syntax that
-is compatible with the proprietary program SPSS.
-If you choose @code{enhanced} then additional syntax will be available.
-The default is @code{enhanced}.
+The CSV format used is an extension to that specified in RFC 4180:
+@table @asis
+@item 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. When a table has a caption and captions are
+enabled, the caption is output just above the table as a single field
+prefixed by @samp{Table:}.
-@item -V
-@item --version
+@item Text
+Text in output is printed as a field on a line by itself. The TITLE
+and SUBTITLE produce similar output, prefixed by @samp{Title:} or
+@samp{Subtitle:}, respectively.
-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 terminates.
+@item Messages
+Errors, warnings, and notes are printed the same way as text.
+@item Charts
+Charts are not included in CSV output.
@end table
+Successive output items are separated by a blank line.
-@node The graphic user interface
+@node Invoking PSPPIRE
+@chapter Invoking @command{psppire}
@section The graphic user interface
-
@cindex Graphic user interface
@cindex PSPPIRE
+The PSPPIRE graphic user interface for @pspp{} can perform all
+functionality of the command line interface. In addition it gives an
+instantaneous view of the data, variables and statistical output.
+
The graphic user interface can be started by typing @command{psppire} at a
command prompt.
Alternatively many systems have a system of interactive menus or buttons
from which @command{psppire} can be started by a series of mouse clicks.
-Once the principles of the PSPP system are understood,
+Once the principles of the @pspp{} system are understood,
the graphic user interface is designed to be largely intuitive, and
for this reason is covered only very briefly by this manual.
projects / pspp / blobdiff