docs
[pspp] / doc / invoking.texi
index b37d59564b642e542dd4c86c071feef80a448fe5..3044efd48b113182802ef15c3dc882b47d86b415 100644 (file)
@@ -1,23 +1,33 @@
+@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
-@cindex PSPP, invoking
+@cindex @pspp{}, invoking
 
-PSPP has two separate user interfaces.  This chapter describes
-@command{pspp}, PSPP's command-line driven text-based user interface.
+@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.
+interface to @pspp{}.
 
 The sections below describe the @command{pspp} program's command-line
 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 SVG and PNG 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
@@ -42,6 +52,7 @@ corresponding short options.
 -O format=@var{format}
 -O device=@{terminal|listing@}
 --no-output
+--table-look=@var{file}
 -e, --error-file=@var{error-file}
 @end example
 
@@ -70,53 +81,71 @@ corresponding short options.
 @end example
 @end table
 
-@table @code
+@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
+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 -o @var{output-file}
-Write output to @var{output-file}.  PSPP has several different output
+@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.
+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, @i{e.g.}@: @file{pspp.pdf} for PDF output.
 
-@item -O @var{option}=@var{value}
+@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 -O format=@var{format}
-PSPP uses the extension of the file name given on @option{-o} to
+@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 -O device=@{terminal|listing@}
-Sets whether PSPP considers the output device configured by the
+@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 --no-output
+@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 -e @var{error-file}
-@itemx --error-file=@var{error-file}
-Configures a file to receive PSPP error, warning, and note messages in
+@item @option{--table-look=@var{file}}
+Reads a table style from @var{file} and applies it to all @pspp{}
+table output.  The file should be a TableLook @file{.stt} or
+@file{.tlo} file.  @pspp{} searches for @var{file} in the current
+directory, then in @file{.pspp/looks} in the user's home directory,
+then in a @file{looks} subdirectory inside @pspp{}'s data directory
+(usually @file{/usr/local/share/pspp}).  If @pspp{} cannot find
+@var{file} under the given name, it also tries adding a @file{.stt}
+extension.
+
+When this option is not specified, @pspp{} looks for
+@file{default.stt} using the algorithm above, and otherwise it falls
+back to a default built-in style.
+
+Using @code{SET TLOOK} in @pspp{} syntax overrides the style set on
+the command line (@pxref{SET}).
+
+@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
@@ -124,94 +153,114 @@ 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 -I @var{dir}
-@itemx --include=@var{dir}
-Appends @var{dir} to the set of directories searched by INCLUDE
-(@pxref{INCLUDE}) and INSERT (@pxref{INSERT}).
+@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 -I-
-@itemx --no-include
+@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
+user's home directory, followed by @pspp{}'s system configuration
 directory (usually @file{/etc/pspp} or @file{/usr/local/etc/pspp}).
 
-@item -b
-@item --batch
-@item -i
-@itemx --interactive
+@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 -r
-@itemx --no-statrc
-Disables running @file{rc} at PSPP startup time.
+@item @option{-r}
+@itemx @option{--no-statrc}
+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 -a @{enhanced|compatible@}
-@itemx --algorithm=@{enhanced|compatible@}
-With @code{enhanced}, the default, PSPP uses the best implemented
+@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
+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 -x @{enhanced|compatible@}
-@itemx --syntax=@{enhanced|compatible@}
-With @code{enhanced}, the default, PSPP accepts its own extensions
+@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.
+@code{compatible}, @pspp{} rejects syntax that uses these extensions.
 
-@item --syntax-encoding=@var{encoding}
+@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
+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 --help
-Prints a message describing PSPP command-line syntax and the available
+@item @option{--help}
+Prints a message describing @pspp{} command-line syntax and the available
 device formats, then exits.
 
-@item -V
-@itemx --version
-Prints a brief message listing PSPP's version, warranties you don't
+@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 -s
-@itemx --safer
-Disables certain unsafe operations.  This includes the ERASE and
-HOST commands, as well as use of pipes as input and output files.
+@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.
 
-@item --testing-mode
-Invoke heuristics to assist with testing PSPP.  For use by @code{make
-check} and similar scripts.
+@item @option{--testing-mode}
+Invoke heuristics to assist with testing @pspp{}.  For use
+by @command{make check} and similar scripts.
 @end table
 
-@node PDF PostScript and SVG Output Options
-@section PDF, PostScript, and SVG Output Options
-
-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.
+@node PDF PostScript SVG and PNG Output Options
+@section PDF, PostScript, SVG, and PNG Output Options
+@cindex PDF
+@cindex Postscript
+@cindex SVG
+@cindex PNG
+
+To produce output in PDF, PostScript, SVG, or PNG 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.
+
+PDF, PostScript, and SVG use real units: each dimension among the
+options listed below may have a 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.
+
+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 @code{-2} suffix, the
+third with a @code{-3} suffix, and so on.
 
-PDF, PostScript, and SVG output is only available if your installation
-of PSPP was compiled with the Cairo library.
-
-@table @code
-@item -O format=@{pdf|ps|svg@}
+@table @asis
+@item @option{-O format=@{pdf|ps|svg|png@}}
 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}.
+given on @option{-o} does not end in @file{.pdf}, @file{.ps},
+@file{.svg}, or @file{.png}.
 
-@item -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}).
+@item @option{-O paper-size=@var{paper-size}}
+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
@@ -221,143 +270,164 @@ 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 -O orientation=@var{orientation}
+@item @option{-O foreground-color=@var{color}}
+Sets @var{color} as the default color for lines and text.  Use a CSS
+color format (e.g.@: @code{#@var{rr}@var{gg}@var{bb}}) or name (e.g.@:
+@code{black}) as @var{color}.
+
+@item @option{-O orientation=@var{orientation}}
 Either @code{portrait} or @code{landscape}.  Default: @code{portrait}.
 
-@item -O left-margin=@var{dimension}
-@itemx -O right-margin=@var{dimension}
-@itemx -O top-margin=@var{dimension}
-@itemx -O bottom-margin=@var{dimension}
+@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 -O prop-font=@var{font-name}
-@itemx -O emph-font=@var{font-name}
-@itemx -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.
+@item @option{-O prop-font=@var{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 @code{serif}, emphasis font @code{serif
-italic}, fixed-pitch font @code{monospace}.
+Default: proportional font @code{Sans Serif}.
 
-@item -O font-size=@var{font-size}
+@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 -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 -O line-spacing=@var{dimension}
-Sets the spacing between the lines in a double line in a table.
-Default: @code{1pt}.
-
-@item -O line-width=@var{dimension}
-Sets the width of the lines used in tables.  Default: @code{0.5pt}.
+@item @option{-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.
+
+@item @option{-O outline=@var{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 @option{-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.)
+
+@item @option{-O font-resolution=@var{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 @math{10 / 72 * 96 = 13.3} pixels.  Use a larger @var{dpi} to
+enlarge text output, or a smaller @var{dpi} to shrink it.
 @end table
 
-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
+@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
+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 @code
-@item -O format=txt
+@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 -O charts=@{@var{template}.png|none@}
+@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 -O paginate=@var{boolean}
-If set, PSPP writes an ASCII formfeed the end of every page.  Default:
-@code{off}.
-
-@item -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 -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 -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 -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 -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 -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 -O emphasis=@{none|bold|underline@}
+Specify @code{none} to disable chart output.
+
+@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
+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 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
+@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.
+The default is @code{unicode} if the locale's character encoding is "UTF-8"
+or @code{ascii} otherwise.
+
+@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 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
 To produce output in HTML format, specify @option{-o @var{file}} on
-the PSPP command line, optionally followed by any of the options shown
+the @pspp{} command line, optionally followed by any of the options shown
 in the table below to customize the output format.
 
-@table @code
-@item -O format=html
+@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}.
 
-@item -O charts=@{@var{template}.png|none@}
+@item @option{-O charts=@{@var{template}.png|none@}}
 Sets the name used for chart files.  @xref{Plain Text Output Options},
 for details.
+
+@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.
+
+@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.
+The default value is true.
+
 @end table
 
 @node OpenDocument Output Options
 @section OpenDocument Output Options
 
 To produce output as an OpenDocument text (ODT) document, specify
-@option{-o @var{file}} on the PSPP command line.  If @var{file} does
+@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}.
 
-ODT support is only available if your installation of PSPP was
+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.
@@ -366,20 +436,20 @@ The OpenDocument output format does not have any configurable options.
 @section Comma-Separated Value Output Options
 
 To produce output in comma-separated value (CSV) format, specify
-@option{-o @var{file}} on the PSPP command line, optionally followed
+@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.
 
-@table @code
-@item -O format=csv
+@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 -O separator=@var{field-separator}
+@item @option{-O separator=@var{field-separator}}
 Sets the character used to separate fields.  Default: a comma
 (@samp{,}).
 
-@item -O quote=@var{qualifier}
+@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
@@ -387,8 +457,13 @@ 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 -O captions=@var{boolean}
-Whether table captions should be printed.  Default: @code{on}.
+@item @option{-O titles=@var{boolean}}
+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:
@@ -398,9 +473,24 @@ 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
@@ -422,15 +512,15 @@ Successive output items are separated by a blank line.
 @cindex Graphic user interface
 @cindex PSPPIRE
 
-The PSPPIRE graphic user interface for PSPP can perform all
+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 
+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.