+@c PSPP - a program for statistical analysis.
+@c Copyright (C) 2017, 2020 Free Software Foundation, Inc.
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+@c A copy of the license is included in the section entitled "GNU
+@c Free Documentation License".
+@c
@node Invoking PSPP
@chapter Invoking @command{pspp}
@cindex invocation
interface.
@menu
-* Main Options::
-* PDF PostScript and SVG Output Options::
-* Plain Text Output Options::
-* HTML Output Options::
-* OpenDocument Output Options::
-* Comma-Separated Value Output Options::
+* Main Options::
+* PDF PostScript and SVG Output Options::
+* Plain Text Output Options::
+* TeX Output Options::
+* HTML Output Options::
+* OpenDocument Output Options::
+* Comma-Separated Value Output Options::
@end menu
@node Main Options
If no @option{-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.@: @file{pspp.pdf} for PDF output.
+based on the format, @i{e.g.}@: @file{pspp.pdf} for PDF output.
@item @option{-O @var{option}=@var{value}}
Sets an option for the output file configured by a preceding
@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
+specifying an alternate format, @i{e.g.}@: @option{-o pspp.out -O format=html} to
write HTML to a file named @file{pspp.out}. Use @option{--help} to
list the available formats.
@item @option{-r}
@itemx @option{--no-statrc}
-Disables running @file{rc} at @pspp{} startup time.
+By default, at startup @pspp{} searches for a file named @file{rc} in
+the include path (described above) and, if it finds one, runs the
+commands in it. This option disables this behavior.
@item @option{-a @{enhanced|compatible@}}
@itemx @option{--algorithm=@{enhanced|compatible@}}
@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}).
+Paper size, as a name (@i{e.g.}@: @code{a4}, @code{letter}) or
+measurements (@i{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
@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 to
+Sets @var{color} as the color to be used for the background or foreground to
be used for charts.
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.
If charts are disabled, this option has no effect.
-
-@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 width=@var{columns}}
+Width of a page, in columns. If unspecified or given as @code{auto},
+the default is the width of the terminal, for interactive output, or
+the WIDTH setting (@pxref{SET}), for output to a file.
@item @option{-O box=@{ascii|unicode@}}
-Sets the characters used for lines in tables.
-If set to
+Sets the characters used for lines in tables.
+If set to
@code{ascii} the characters @samp{-}, @samp{|}, and @samp{+} for single-width
lines and @samp{=} and @samp{#} for double-width lines are used.
If set to @code{unicode} then Unicode box drawing characters will be used.
you might pass the output. Default: @code{none}.
@end table
+@node TeX Output Options
+@section TeX Output Options
+@cindex @TeX{}
+@cindex tex
+
+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 @option{-o @var{file}} on the @pspp{} command line where
+@var{file} is a file name ending in @file{.tex}, or you can specify
+@option{-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.
+
@node HTML Output Options
@section HTML Output Options
@cindex HTML
Decorate the tables with borders. If set to false, the tables produced
will have no borders. The default value is true.
+@item @option{-O bare=@var{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 @code{body} element. The default value is false.
+
@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.
string, then fields are never quoted.
@item @option{-O titles=@var{boolean}}
-Whether table titles should be printed. Default: @code{on}.
+Whether table titles (brief descriptions) should be printed. Default:
+@code{on}.
+
+@item @option{-O captions=@var{boolean}}
+Whether table captions (more extensive descriptions) should be
+printed. Default: on.
@end table
The CSV format used is an extension to that specified in RFC 4180:
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:}.
+output as empty fields.
+
+@item 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 @samp{Table:}.
+
+@item 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
+@samp{Caption:}.
+
+@item Footnotes
+Within a table, footnote markers are output as bracketed letters
+following the cell's contents, @i{e.g.}@tie{}@samp{[a]}, @samp{[b]},
+@enddots{} The footnotes themselves are output following the body of
+the table, as a separate two-column table introduced with a line that
+says @samp{Footnotes:}. Each row in the table represent one footnote:
+the first column is the marker, the second column is the text.
@item Text
Text in output is printed as a field on a line by itself. The TITLE
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
+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
+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.