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

   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".
   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 -@w{-}help}
  35
  36 @t{pspp-output -@w{-}version}
  37 @end display
  38
  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.
  42
  43 @menu
  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::
  49 @end menu
  50
  51 @node The pspp-output detect Command
  52 @section The @code{detect} Command
  53
  54 @display
  55 @t{pspp-output} @t{detect} @var{file}
  56 @end display
  57
  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.
  62
  63 @node The pspp-output dir Command
  64 @section The @code{dir} Command
  65
  66 @display
  67 @t{pspp-output} [@var{options}] @t{dir} @var{file}
  68 @end display
  69
  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.
  74
  75 The following additional option for @command{dir} is intended mainly
  76 for use by PSPP developers:
  77
  78 @table @option
  79 @item --member-names
  80 Also show the names of the Zip members associated with each object.
  81 @end table
  82
  83 @node The pspp-output convert Command
  84 @section The @code{convert} Command
  85
  86 @display
  87 @t{pspp-output} [@var{options}] @t{convert} @var{source} @var{destination}
  88 @end display
  89
  90 Reads SPV file @var{source} and converts it to another format, writing
  91 the output to @var{destination}.
  92
  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.
  96
  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:
 100
 101 @table @option
 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.
 106
 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.
 110
 111 @item -F
 112 @itemx --force
 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.
 116
 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.
 120 @end table
 121
 122 @node The pspp-output get-table-look Command
 123 @section The @code{get-table-look} Command
 124
 125 @display
 126 @t{pspp-output} [@var{options}] @t{get-table-look} @var{source} @var{destination}
 127 @end display
 128
 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.
 134
 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.
 138
 139 @node Input Selection Options
 140 @section Input Selection Options
 141
 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:
 147
 148 @table @option
 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:
 153
 154 @quotation
 155 @code{charts headings logs models tables texts trees warnings
 156 outlineheaders pagetitle notes unknown other}
 157 @end quotation
 158
 159 Use @option{--select=help} to print this list of classes.
 160
 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.
 168
 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.
 176
 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.
 181
 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.
 185
 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.
 191
 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.
 197
 198 @item --show-hidden
 199 Include hidden output objects in the output.  By default, they are
 200 excluded.
 201
 202 @item --or
 203 Separates two sets of selection options.  Objects selected by either
 204 set of options are included in the output.
 205 @end table
 206
 207 The following additional input selection options are intended mainly
 208 for use by PSPP developers:
 209
 210 @table @option
 211 @item --errors
 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.
 215
 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.
 224
 225 @item --member-names
 226 Displays the name of the Zip member or members associated with each
 227 object just above the object itself.
 228 @end table