work on docs

[pspp] / doc / pspp-output.texi

@c PSPP - a program for statistical analysis.
@c Copyright (C) 2019, 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-output
@chapter Invoking @command{pspp-output}
@cindex Invocation
@cindex @command{pspp-output}

@command{pspp-output} is a command-line utility accompanying @pspp{}.
It supports multiple operations on SPSS viewer or @file{.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 @file{.spo} files.
@command{pspp-output} does not support this format.

@command{pspp-options} may be invoked in the following ways:

@display
@t{pspp-output} @t{detect} @var{file}

@t{pspp-output} [@var{options}] @t{dir} @var{file}

@t{pspp-output} [@var{options}] @t{convert} @var{source} @var{destination}

@t{pspp-output} [@var{options}] @t{get-table-look} @var{source} @var{destination}

@t{pspp-output} [@var{options}] @t{convert-table-look} @var{source} @var{destination}

@t{pspp-output -@w{-}help}

@t{pspp-output -@w{-}version}
@end display

Each of these forms is documented separately below.
@command{pspp-output} also has several undocumented command forms that
developers may find useful for debugging.

@menu
* The pspp-output detect Command::
* The pspp-output dir Command::
* The pspp-output convert Command::
* The pspp-output get-table-look Command::
* The pspp-output convert-table-look Command::
* Input Selection Options::
@end menu

@node The pspp-output detect Command
@section The @code{detect} Command

@display
@t{pspp-output} @t{detect} @var{file}
@end display

When @var{file} is an SPV file, @command{pspp-output} exits
successfully without outputting anything.  When @var{file} is not an
SPV file or some other error occurs, @command{pspp-output} prints an
error message and exits with a failure indication.

@node The pspp-output dir Command
@section The @code{dir} Command

@display
@t{pspp-output} [@var{options}] @t{dir} @var{file}
@end display

Prints on stdout a table of contents for SPV file @var{file}.  By
default, this table lists every object in the file, except for hidden
objects.  @xref{Input Selection Options}, for information on the
options available to select a subset of objects.

The following additional option for @command{dir} is intended mainly
for use by PSPP developers:

@table @option
@item --member-names
Also show the names of the Zip members associated with each object.
@end table

@node The pspp-output convert Command
@section The @code{convert} Command

@display
@t{pspp-output} [@var{options}] @t{convert} @var{source} @var{destination}
@end display

Reads SPV file @var{source} and converts it to another format, writing
the output to @var{destination}.

By default, the intended format for @var{destination} is inferred
based on its extension, in the same way that the @command{pspp}
program does for its output files.  @xref{Invoking PSPP}, for details.

@xref{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:

@table @option
@item -O format=@var{format}
Overrides the format inferred from the output file's extension.  Use
@option{--help} to list the available formats.  @xref{Invoking PSPP},
for details of the available output formats.

@item -O @var{option}=@var{value}
Sets an option for the output file format.  @xref{Invoking PSPP}, for
details of the available output options.

@item -F
@itemx --force
By default, if the source is corrupt or otherwise cannot be processed,
the destination is not written.  With @option{-F} or @option{--force},
the destination is written as best it can, even with errors.

@item --table-look=@var{file}
Reads a table style from @var{file} and applies it to all of the
output tables.  The file should be a TableLook @file{.stt} or
@file{.tlo} file.
@end table

@node The pspp-output get-table-look Command
@section The @code{get-table-look} Command

@display
@t{pspp-output} [@var{options}] @t{get-table-look} @var{source} @var{destination}
@end display

Reads SPV file @var{source}, applies any selection options
(@pxref{Input Selection Options}), picks the first table from the
selected object, extracts the TableLook from that table, and writes it
to @var{destination} (typically with an @file{.stt} extension) in the
TableLook XML format.

Use @samp{-} for @var{source} to instead write the default look to
@var{destination}.

The user may use the TableLook file to change the style of tables in
other files, by passing it to the @option{--table-look} option on the
@code{convert} command.

@node The pspp-output convert-table-look Command
@section The @code{convert-table-look} Command

@display
@t{pspp-output} [@var{options}] @t{convert-table-look} @var{source} @var{destination}
@end display

Reads @file{.stt} or @file{.tlo} file @var{source}, and writes it back
to @var{destination} (typically with an @file{.stt} extension) in the
TableLook XML format.  This is useful for converting a TableLook
@file{.tlo} file from SPSS 15 or earlier into the newer @file{.stt}
format.

@node Input Selection Options
@section Input Selection Options

The @command{dir} and @command{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:

@table @option
@item --select=@r{[}^@r{]}@var{class}@dots{}
Include only objects of the given @var{class}; with leading @samp{^},
include only objects not in the class.  Use commas to separate
multiple classes.  The supported classes are:

@quotation
@code{charts headings logs models tables texts trees warnings
outlineheaders pagetitle notes unknown other}
@end quotation

Use @option{--select=help} to print this list of classes.

@item --commands=@r{[}^@r{]}@var{command}@dots{}
@itemx --subtypes=@r{[}^@r{]}@var{subtype}@dots{}
@itemx --labels=@r{[}^@r{]}@var{label}@dots{}
Include only objects with the specified @var{command}, @var{subtype},
or @var{label}.  With a leading @samp{^}, 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 @option{--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
@command{pspp-output} program's @command{dir} command to print command
identifiers in particular output.

The @option{--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 @command{dir} will print them.

The @option{--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.

@item --nth-commands=@var{n}@dots{}
Include only objects from the @var{n}th command that matches
@option{--command} (or the @var{n}th command overall if
@option{--command} is not specified), where @var{n} is 1 for the first
command, 2 for the second, and so on.

@item --instances=@var{instance}@dots{}
Include the specified @var{instance} of an object that matches the
other criteria within a single command.  The @var{instance} may be a
number (1 for the first instance, 2 for the second, and so on) or
@code{last} for the last instance.

@item --show-hidden
Include hidden output objects in the output.  By default, they are
excluded.

@item --or
Separates two sets of selection options.  Objects selected by either
set of options are included in the output.
@end table

The following additional input selection options are intended mainly
for use by PSPP developers:

@table @option
@item --errors
Include only objects that cause an error when read.  With the
@command{convert} command, this is most useful in conjunction with the
@option{--force} option.

@item --members=@var{member}@dots{}
Include only the objects that include a listed Zip file @var{member}.
More than one name may be included, comma-separated.  The members in
an SPV file may be listed with the @command{dir} command by adding the
@option{--show-members} option or with the @command{zipinfo} program
included with many operating systems.  Error messages that
@command{pspp-output} prints when it reads SPV files also often
include member names.

@item --member-names
Displays the name of the Zip member or members associated with each
object just above the object itself.
@end table