1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2019 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 -@w{-}help}
36 @t{pspp-output -@w{-}version}
39 Each of these forms is documented separately below.
40 @command{pspp-output} also has several undocumented command forms that
41 developers may find useful for debugging.
44 * The pspp-output detect Command::
45 * The pspp-output dir Command::
46 * The pspp-output convert Command::
47 * The pspp-output get-table-look Command::
48 * Input Selection Options::
51 @node The pspp-output detect Command
52 @section The @code{detect} Command
55 @t{pspp-output} @t{detect} @var{file}
58 When @var{file} is an SPV file, @command{pspp-output} exits
59 successfully without outputting anything. When @var{file} is not an
60 SPV file or some other error occurs, @command{pspp-output} prints an
61 error message and exits with a failure indication.
63 @node The pspp-output dir Command
64 @section The @code{dir} Command
67 @t{pspp-output} [@var{options}] @t{dir} @var{file}
70 Prints on stdout a table of contents for SPV file @var{file}. By
71 default, this table lists every object in the file, except for hidden
72 objects. @xref{Input Selection Options}, for information on the
73 options available to select a subset of objects.
75 The following additional option for @command{dir} is intended mainly
76 for use by PSPP developers:
80 Also show the names of the Zip members associated with each object.
83 @node The pspp-output convert Command
84 @section The @code{convert} Command
87 @t{pspp-output} [@var{options}] @t{convert} @var{source} @var{destination}
90 Reads SPV file @var{source} and converts it to another format, writing
91 the output to @var{destination}.
93 By default, the intended format for @var{destination} is inferred
94 based on its extension, in the same way that the @command{pspp}
95 program does for its output files. @xref{Invoking PSPP}, for details.
97 @xref{Input Selection Options}, for information on the options
98 available to select a subset of objects to include in the output. The
99 following additional options are accepted:
102 @item -O format=@var{format}
103 Overrides the format inferred from the output file's extension. Use
104 @option{--help} to list the available formats. @xref{Invoking PSPP},
105 for details of the available output formats.
107 @item -O @var{option}=@var{value}
108 Sets an option for the output file format. @xref{Invoking PSPP}, for
109 details of the available output options.
113 By default, if the source is corrupt or otherwise cannot be processed,
114 the destination is not written. With @option{-F} or @option{--force},
115 the destination is written as best it can, even with errors.
117 @item --table-look=@var{file}
118 Reads a table style from @var{file} and applies it to all of the
119 output tables. The file should a TableLook @file{.stt} file.
122 @node The pspp-output get-table-look Command
123 @section The @code{get-table-look} Command
126 @t{pspp-output} [@var{options}] @t{get-table-look} @var{source} @var{destination}
129 Reads SPV file @var{source}, applies any selection options
130 (@pxref{Input Selection Options}), picks the first table from the
131 selected object, extracts the TableLook from that table, and writes it
132 to @var{destination} (typically with an @file{.stt} extension) in the
133 TableLook XML format.
135 The user may use the TableLook file to change the style of tables in
136 other files, by passing it to the @option{--table-look} option on the
137 @code{convert} command.
139 @node Input Selection Options
140 @section Input Selection Options
142 The @command{dir} and @command{convert} commands, by default, operate
143 on all of the objects in the source SPV file, except for objects that
144 are not visible in the output viewer window. The user may specify
145 these options to select a subset of the input objects. When multiple
146 options are used, only objects that satisfy all of them are selected:
149 @item --select=@r{[}^@r{]}@var{class}@dots{}
150 Include only objects of the given @var{class}; with leading @samp{^},
151 include only objects not in the class. Use commas to separate
152 multiple classes. The supported classes are:
155 @code{charts headings logs models tables texts trees warnings
156 outlineheaders pagetitle notes unknown other}
159 Use @option{--select=help} to print this list of classes.
161 @item --commands=@r{[}^@r{]}@var{command}@dots{}
162 @itemx --subtypes=@r{[}^@r{]}@var{subtype}@dots{}
163 @itemx --labels=@r{[}^@r{]}@var{label}@dots{}
164 Include only objects with the specified @var{command}, @var{subtype},
165 or @var{label}. With a leading @samp{^}, include only the objects
166 that do not match. Multiple values may be specified separated by
167 commas. An asterisk at the end of a value acts as a wildcard.
169 The @option{--command} option matches command identifiers, case
170 insensitively. All of the objects produced by a single command use
171 the same, unique command identifier. Command identifiers are always
172 in English regardless of the language used for output. They often
173 differ from the command name in PSPP syntax. Use the
174 @command{pspp-output} program's @command{dir} command to print command
175 identifiers in particular output.
177 The @option{--subtypes} option matches particular tables within a
178 command, case insensitively. Subtypes are not necessarily unique: two
179 commands that produce similar output tables may use the same subtype.
180 Subtypes are always in English and @command{dir} will print them.
182 The @option{--labels} option matches the labels in table output (that
183 is, the table titles). Labels are affected by the output language,
184 variable names and labels, split file settings, and other factors.
186 @item --nth-commands=@var{n}@dots{}
187 Include only objects from the @var{n}th command that matches
188 @option{--command} (or the @var{n}th command overall if
189 @option{--command} is not specified), where @var{n} is 1 for the first
190 command, 2 for the second, and so on.
192 @item --instances=@var{instance}@dots{}
193 Include the specified @var{instance} of an object that matches the
194 other criteria within a single command. The @var{instance} may be a
195 number (1 for the first instance, 2 for the second, and so on) or
196 @code{last} for the last instance.
199 Include hidden output objects in the output. By default, they are
203 Separates two sets of selection options. Objects selected by either
204 set of options are included in the output.
207 The following additional input selection options are intended mainly
208 for use by PSPP developers:
212 Include only objects that cause an error when read. With the
213 @command{convert} command, this is most useful in conjunction with the
214 @option{--force} option.
216 @item --members=@var{member}@dots{}
217 Include only the objects that include a listed Zip file @var{member}.
218 More than one name may be included, comma-separated. The members in
219 an SPV file may be listed with the @command{dir} command by adding the
220 @option{--show-members} option or with the @command{zipinfo} program
221 included with many operating systems. Error messages that
222 @command{pspp-output} prints when it reads SPV files also often
223 include member names.
226 Displays the name of the Zip member or members associated with each
227 object just above the object itself.