pintos-os.org Git - pspp/blob - doc/pspp-output.texi

   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".
   9 @c
  10 @node Invoking pspp-output
  11 @chapter Invoking @command{pspp-output}
  12 @cindex Invocation
  13 @cindex @command{pspp-output}
  14
  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.
  19
  20 SPSS 15 and earlier versions instead use @file{.spo} files.
  21 @command{pspp-output} does not support this format.
  22
  23 @command{pspp-options} may be invoked in the following ways:
  24
  25 @display
  26 @t{pspp-output} @t{detect} @var{file}
  27
  28 @t{pspp-output} [@var{options}] @t{dir} @var{file}
  29
  30 @t{pspp-output} [@var{options}] @t{convert} @var{source} @var{destination}
  31
  32 @t{pspp-output} [@var{options}] @t{get-table-look} @var{source} @var{destination}
  33
  34 @t{pspp-output} [@var{options}] @t{convert-table-look} @var{source} @var{destination}
  35
  36 @t{pspp-output -@w{-}help}
  37
  38 @t{pspp-output -@w{-}version}
  39 @end display
  40
  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.
  44
  45 @menu
  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::
  52 @end menu
  53
  54 @node The pspp-output detect Command
  55 @section The @code{detect} Command
  56
  57 @display
  58 @t{pspp-output} @t{detect} @var{file}
  59 @end display
  60
  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.
  65
  66 @node The pspp-output dir Command
  67 @section The @code{dir} Command
  68
  69 @display
  70 @t{pspp-output} [@var{options}] @t{dir} @var{file}
  71 @end display
  72
  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.
  77
  78 The following additional option for @command{dir} is intended mainly
  79 for use by PSPP developers:
  80
  81 @table @option
  82 @item --member-names
  83 Also show the names of the Zip members associated with each object.
  84 @end table
  85
  86 @node The pspp-output convert Command
  87 @section The @code{convert} Command
  88
  89 @display
  90 @t{pspp-output} [@var{options}] @t{convert} @var{source} @var{destination}
  91 @end display
  92
  93 Reads SPV file @var{source} and converts it to another format, writing
  94 the output to @var{destination}.
  95
  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.
  99
 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:
 103
 104 @table @option
 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.
 109
 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.
 113
 114 @item -F
 115 @itemx --force
 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.
 119
 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
 123 @file{.tlo} file.
 124 @end table
 125
 126 @node The pspp-output get-table-look Command
 127 @section The @code{get-table-look} Command
 128
 129 @display
 130 @t{pspp-output} [@var{options}] @t{get-table-look} @var{source} @var{destination}
 131 @end display
 132
 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.
 138
 139 Use @samp{-} for @var{source} to instead write the default look to
 140 @var{destination}.
 141
 142 The user may use the TableLook file to change the style of tables in
 143 other files, by passing it to the @option{--table-look} option on the
 144 @code{convert} command.
 145
 146 @node The pspp-output convert-table-look Command
 147 @section The @code{convert-table-look} Command
 148
 149 @display
 150 @t{pspp-output} [@var{options}] @t{convert-table-look} @var{source} @var{destination}
 151 @end display
 152
 153 Reads @file{.stt} or @file{.tlo} file @var{source}, and writes it back
 154 to @var{destination} (typically with an @file{.stt} extension) in the
 155 TableLook XML format.  This is useful for converting a TableLook
 156 @file{.tlo} file from SPSS 15 or earlier into the newer @file{.stt}
 157 format.
 158
 159 @node Input Selection Options
 160 @section Input Selection Options
 161
 162 The @command{dir} and @command{convert} commands, by default, operate
 163 on all of the objects in the source SPV file, except for objects that
 164 are not visible in the output viewer window.  The user may specify
 165 these options to select a subset of the input objects.  When multiple
 166 options are used, only objects that satisfy all of them are selected:
 167
 168 @table @option
 169 @item --select=@r{[}^@r{]}@var{class}@dots{}
 170 Include only objects of the given @var{class}; with leading @samp{^},
 171 include only objects not in the class.  Use commas to separate
 172 multiple classes.  The supported classes are:
 173
 174 @quotation
 175 @code{charts headings logs models tables texts trees warnings
 176 outlineheaders pagetitle notes unknown other}
 177 @end quotation
 178
 179 Use @option{--select=help} to print this list of classes.
 180
 181 @item --commands=@r{[}^@r{]}@var{command}@dots{}
 182 @itemx --subtypes=@r{[}^@r{]}@var{subtype}@dots{}
 183 @itemx --labels=@r{[}^@r{]}@var{label}@dots{}
 184 Include only objects with the specified @var{command}, @var{subtype},
 185 or @var{label}.  With a leading @samp{^}, include only the objects
 186 that do not match.  Multiple values may be specified separated by
 187 commas.  An asterisk at the end of a value acts as a wildcard.
 188
 189 The @option{--command} option matches command identifiers, case
 190 insensitively.  All of the objects produced by a single command use
 191 the same, unique command identifier.  Command identifiers are always
 192 in English regardless of the language used for output.  They often
 193 differ from the command name in PSPP syntax.  Use the
 194 @command{pspp-output} program's @command{dir} command to print command
 195 identifiers in particular output.
 196
 197 The @option{--subtypes} option matches particular tables within a
 198 command, case insensitively.  Subtypes are not necessarily unique: two
 199 commands that produce similar output tables may use the same subtype.
 200 Subtypes are always in English and @command{dir} will print them.
 201
 202 The @option{--labels} option matches the labels in table output (that
 203 is, the table titles).  Labels are affected by the output language,
 204 variable names and labels, split file settings, and other factors.
 205
 206 @item --nth-commands=@var{n}@dots{}
 207 Include only objects from the @var{n}th command that matches
 208 @option{--command} (or the @var{n}th command overall if
 209 @option{--command} is not specified), where @var{n} is 1 for the first
 210 command, 2 for the second, and so on.
 211
 212 @item --instances=@var{instance}@dots{}
 213 Include the specified @var{instance} of an object that matches the
 214 other criteria within a single command.  The @var{instance} may be a
 215 number (1 for the first instance, 2 for the second, and so on) or
 216 @code{last} for the last instance.
 217
 218 @item --show-hidden
 219 Include hidden output objects in the output.  By default, they are
 220 excluded.
 221
 222 @item --or
 223 Separates two sets of selection options.  Objects selected by either
 224 set of options are included in the output.
 225 @end table
 226
 227 The following additional input selection options are intended mainly
 228 for use by PSPP developers:
 229
 230 @table @option
 231 @item --errors
 232 Include only objects that cause an error when read.  With the
 233 @command{convert} command, this is most useful in conjunction with the
 234 @option{--force} option.
 235
 236 @item --members=@var{member}@dots{}
 237 Include only the objects that include a listed Zip file @var{member}.
 238 More than one name may be included, comma-separated.  The members in
 239 an SPV file may be listed with the @command{dir} command by adding the
 240 @option{--show-members} option or with the @command{zipinfo} program
 241 included with many operating systems.  Error messages that
 242 @command{pspp-output} prints when it reads SPV files also often
 243 include member names.
 244
 245 @item --member-names
 246 Displays the name of the Zip member or members associated with each
 247 object just above the object itself.
 248 @end table