1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2019, 2020 Free Software Foundation, Inc.
3 @c Permission is granted to copy, distribute and/or modify this document
4 @c under the terms of the GNU Free Documentation License, Version 1.3
5 @c or any later version published by the Free Software Foundation;
6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
7 @c A copy of the license is included in the section entitled "GNU
8 @c Free Documentation License".
10 @node Invoking pspp-output
11 @chapter Invoking @command{pspp-output}
13 @cindex @command{pspp-output}
15 @command{pspp-output} is a command-line utility accompanying @pspp{}.
16 It supports multiple operations on SPSS viewer or @file{.spv} files,
17 here called SPV files. SPSS 16 and later writes SPV files to
18 represent the contents of its output editor.
20 SPSS 15 and earlier versions instead use @file{.spo} files.
21 @command{pspp-output} does not support this format.
23 @command{pspp-options} may be invoked in the following ways:
26 @t{pspp-output} @t{detect} @var{file}
28 @t{pspp-output} [@var{options}] @t{dir} @var{file}
30 @t{pspp-output} [@var{options}] @t{convert} @var{source} @var{destination}
32 @t{pspp-output} [@var{options}] @t{get-table-look} @var{source} @var{destination}
34 @t{pspp-output} [@var{options}] @t{convert-table-look} @var{source} @var{destination}
36 @t{pspp-output -@w{-}help}
38 @t{pspp-output -@w{-}version}
41 Each of these forms is documented separately below.
42 @command{pspp-output} also has several undocumented command forms that
43 developers may find useful for debugging.
46 * The pspp-output detect Command::
47 * The pspp-output dir Command::
48 * The pspp-output convert Command::
49 * The pspp-output get-table-look Command::
50 * The pspp-output convert-table-look Command::
51 * Input Selection Options::
54 @node The pspp-output detect Command
55 @section The @code{detect} Command
58 @t{pspp-output} @t{detect} @var{file}
61 When @var{file} is an SPV file, @command{pspp-output} exits
62 successfully without outputting anything. When @var{file} is not an
63 SPV file or some other error occurs, @command{pspp-output} prints an
64 error message and exits with a failure indication.
66 @node The pspp-output dir Command
67 @section The @code{dir} Command
70 @t{pspp-output} [@var{options}] @t{dir} @var{file}
73 Prints on stdout a table of contents for SPV file @var{file}. By
74 default, this table lists every object in the file, except for hidden
75 objects. @xref{Input Selection Options}, for information on the
76 options available to select a subset of objects.
78 The following additional option for @command{dir} is intended mainly
79 for use by PSPP developers:
83 Also show the names of the Zip members associated with each object.
86 @node The pspp-output convert Command
87 @section The @code{convert} Command
90 @t{pspp-output} [@var{options}] @t{convert} @var{source} @var{destination}
93 Reads SPV file @var{source} and converts it to another format, writing
94 the output to @var{destination}.
96 By default, the intended format for @var{destination} is inferred
97 based on its extension, in the same way that the @command{pspp}
98 program does for its output files. @xref{Invoking PSPP}, for details.
100 @xref{Input Selection Options}, for information on the options
101 available to select a subset of objects to include in the output. The
102 following additional options are accepted:
105 @item -O format=@var{format}
106 Overrides the format inferred from the output file's extension. Use
107 @option{--help} to list the available formats. @xref{Invoking PSPP},
108 for details of the available output formats.
110 @item -O @var{option}=@var{value}
111 Sets an option for the output file format. @xref{Invoking PSPP}, for
112 details of the available output options.
116 By default, if the source is corrupt or otherwise cannot be processed,
117 the destination is not written. With @option{-F} or @option{--force},
118 the destination is written as best it can, even with errors.
120 @item --table-look=@var{file}
121 Reads a table style from @var{file} and applies it to all of the
122 output tables. The file should be a TableLook @file{.stt} or
126 @node The pspp-output get-table-look Command
127 @section The @code{get-table-look} Command
130 @t{pspp-output} [@var{options}] @t{get-table-look} @var{source} @var{destination}
133 Reads SPV file @var{source}, applies any selection options
134 (@pxref{Input Selection Options}), picks the first table from the
135 selected object, extracts the TableLook from that table, and writes it
136 to @var{destination} (typically with an @file{.stt} extension) in the
137 TableLook XML format.
139 The user may use the TableLook file to change the style of tables in
140 other files, by passing it to the @option{--table-look} option on the
141 @code{convert} command.
143 @node The pspp-output convert-table-look Command
144 @section The @code{convert-table-look} Command
147 @t{pspp-output} [@var{options}] @t{convert-table-look} @var{source} @var{destination}
150 Reads @file{.stt} or @file{.tlo} file @var{source}, and writes it back
151 to @var{destination} (typically with an @file{.stt} extension) in the
152 TableLook XML format. This is useful for converting a TableLook
153 @file{.tlo} file from SPSS 15 or earlier into the newer @file{.stt}
156 @node Input Selection Options
157 @section Input Selection Options
159 The @command{dir} and @command{convert} commands, by default, operate
160 on all of the objects in the source SPV file, except for objects that
161 are not visible in the output viewer window. The user may specify
162 these options to select a subset of the input objects. When multiple
163 options are used, only objects that satisfy all of them are selected:
166 @item --select=@r{[}^@r{]}@var{class}@dots{}
167 Include only objects of the given @var{class}; with leading @samp{^},
168 include only objects not in the class. Use commas to separate
169 multiple classes. The supported classes are:
172 @code{charts headings logs models tables texts trees warnings
173 outlineheaders pagetitle notes unknown other}
176 Use @option{--select=help} to print this list of classes.
178 @item --commands=@r{[}^@r{]}@var{command}@dots{}
179 @itemx --subtypes=@r{[}^@r{]}@var{subtype}@dots{}
180 @itemx --labels=@r{[}^@r{]}@var{label}@dots{}
181 Include only objects with the specified @var{command}, @var{subtype},
182 or @var{label}. With a leading @samp{^}, include only the objects
183 that do not match. Multiple values may be specified separated by
184 commas. An asterisk at the end of a value acts as a wildcard.
186 The @option{--command} option matches command identifiers, case
187 insensitively. All of the objects produced by a single command use
188 the same, unique command identifier. Command identifiers are always
189 in English regardless of the language used for output. They often
190 differ from the command name in PSPP syntax. Use the
191 @command{pspp-output} program's @command{dir} command to print command
192 identifiers in particular output.
194 The @option{--subtypes} option matches particular tables within a
195 command, case insensitively. Subtypes are not necessarily unique: two
196 commands that produce similar output tables may use the same subtype.
197 Subtypes are always in English and @command{dir} will print them.
199 The @option{--labels} option matches the labels in table output (that
200 is, the table titles). Labels are affected by the output language,
201 variable names and labels, split file settings, and other factors.
203 @item --nth-commands=@var{n}@dots{}
204 Include only objects from the @var{n}th command that matches
205 @option{--command} (or the @var{n}th command overall if
206 @option{--command} is not specified), where @var{n} is 1 for the first
207 command, 2 for the second, and so on.
209 @item --instances=@var{instance}@dots{}
210 Include the specified @var{instance} of an object that matches the
211 other criteria within a single command. The @var{instance} may be a
212 number (1 for the first instance, 2 for the second, and so on) or
213 @code{last} for the last instance.
216 Include hidden output objects in the output. By default, they are
220 Separates two sets of selection options. Objects selected by either
221 set of options are included in the output.
224 The following additional input selection options are intended mainly
225 for use by PSPP developers:
229 Include only objects that cause an error when read. With the
230 @command{convert} command, this is most useful in conjunction with the
231 @option{--force} option.
233 @item --members=@var{member}@dots{}
234 Include only the objects that include a listed Zip file @var{member}.
235 More than one name may be included, comma-separated. The members in
236 an SPV file may be listed with the @command{dir} command by adding the
237 @option{--show-members} option or with the @command{zipinfo} program
238 included with many operating systems. Error messages that
239 @command{pspp-output} prints when it reads SPV files also often
240 include member names.
243 Displays the name of the Zip member or members associated with each
244 object just above the object itself.