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 modify Command::
  50 * The pspp-output get-table-look Command::
  51 * The pspp-output convert-table-look Command::
  52 * Input Selection Options::
  53 @end menu
  54
  55 @node The pspp-output detect Command
  56 @section The @code{detect} Command
  57
  58 @display
  59 @t{pspp-output} @t{detect} @var{file}
  60 @end display
  61
  62 When @var{file} is an SPV file, @command{pspp-output} exits
  63 successfully without outputting anything.  When @var{file} is not an
  64 SPV file or some other error occurs, @command{pspp-output} prints an
  65 error message and exits with a failure indication.
  66
  67 @node The pspp-output dir Command
  68 @section The @code{dir} Command
  69
  70 @display
  71 @t{pspp-output} [@var{options}] @t{dir} @var{file}
  72 @end display
  73
  74 Prints on stdout a table of contents for SPV file @var{file}.  By
  75 default, this table lists every object in the file, except for hidden
  76 objects.  @xref{Input Selection Options}, for information on the
  77 options available to select a subset of objects.
  78
  79 The following additional option for @command{dir} is intended mainly
  80 for use by PSPP developers:
  81
  82 @table @option
  83 @item --member-names
  84 Also show the names of the Zip members associated with each object.
  85 @end table
  86
  87 @node The pspp-output convert Command
  88 @section The @code{convert} Command
  89
  90 @display
  91 @t{pspp-output} [@var{options}] @t{convert} @var{source} @var{destination}
  92 @end display
  93
  94 Reads SPV file @var{source} and converts it to another format, writing
  95 the output to @var{destination}.
  96
  97 By default, the intended format for @var{destination} is inferred
  98 based on its extension, in the same way that the @command{pspp}
  99 program does for its output files.  @xref{Invoking PSPP}, for details.
 100
 101 @xref{Input Selection Options}, for information on the options
 102 available to select a subset of objects to include in the output.  The
 103 following additional options are accepted:
 104
 105 @table @option
 106 @item -O format=@var{format}
 107 Overrides the format inferred from the output file's extension.  Use
 108 @option{--help} to list the available formats.  @xref{Invoking PSPP},
 109 for details of the available output formats.
 110
 111 @item -O @var{option}=@var{value}
 112 Sets an option for the output file format.  @xref{Invoking PSPP}, for
 113 details of the available output options.
 114
 115 @item -F
 116 @itemx --force
 117 By default, if the source is corrupt or otherwise cannot be processed,
 118 the destination is not written.  With @option{-F} or @option{--force},
 119 the destination is written as best it can, even with errors.
 120
 121 @item --table-look=@var{file}
 122 Reads a table style from @var{file} and applies it to all of the
 123 output tables.  The file should be a TableLook @file{.stt} or
 124 @file{.tlo} file.
 125 @end table
 126
 127 @node The pspp-output modify Command
 128 @section The @code{modify} Command
 129
 130 @display
 131 @t{pspp-output} [@var{options}] @t{modify} @var{file} [@var{new-file}]
 132 @end display
 133
 134 Reads SPV @var{file} and writes out a modified version.  Without
 135 @var{new-file}, the modified file replaces @var{file} in-place.  With
 136 @var{new-file}, @code{pspp-output} writes the modified version as
 137 @var{new-file}.  In the latter case, @code{pspp-output} by default
 138 infers the format of @var{new-file} the intended format for
 139 @var{destination} is inferred based on its extension, in the same way
 140 that the @command{pspp} program does for its output files.
 141 @xref{Invoking PSPP}, for details.
 142
 143 The @code{modify} command includes all objects in @var{file} in its
 144 output, @strong{except} that it deletes objects in formats not yet
 145 understood by PSPP, such as charts.    @xref{Input Selection Options},
 146 for information on the options available to select a subset of objects
 147 to modify while copying them to the output.
 148
 149 The following options specify modifications to be made:
 150
 151 @table @option
 152 @item --set-visible=@var{bool}
 153 Makes the selected visible or invisible, according to @var{bool}.
 154
 155 @item --set-label=@var{label}
 156 Set the selected objects' labels to @var{label}.  Labels appear in the
 157 outline in the PSPPIRE output viewer window and in the outline sidebar
 158 in PDF output.  The @var{label} may contain any of the following
 159 substitution variables:
 160
 161 @table @code
 162 @item )DATE
 163 @itemx )ADATE
 164 @itemx )SDATE
 165 @itemx )EDATE
 166 The current date in format @code{DD-MMM-YYYY}, @code{MM/DD/YYYY},
 167 @code{YYYY/MM/DD}, or @code{DD.MM.YYYY}, respectively.
 168
 169 @item )TIME
 170 @itemx )ETIME
 171 The current time in the format @code{hh:mm:ss}, using a 12-hour or
 172 24-hour clock, respectively.
 173
 174 @item )INDEX
 175 The number of objects modified so far: 1 for the first object, 2 for
 176 the second, and so on.
 177
 178 @item )LABEL
 179 The existing label text.
 180 @end table
 181
 182 For example, to add an index at the beginning of each object's label,
 183 use @option{--set-label=')INDEX. )LABEL'}.
 184
 185 @item --set-title=@var{title}
 186 Sets the titles of selected table objects to @var{title}, which
 187 supports the same substitution variables as @option{--set-label}.
 188
 189 @item --transpose
 190 Transposes rows and columns of selected table objects.
 191
 192 @item --table-look=@var{file}
 193 Reads a table style from @var{file} and applies it to selected table
 194 objects.  The file should be a TableLook @file{.stt} or @file{.tlo}
 195 file.
 196
 197 @item --set-comment=@var{comment}
 198 Sets the comment on the selected table objects to @var{comment}.
 199 Comment text appears as a tooltip when the user hovers over the table
 200 in the PSPPIRE output viewer window or in exported HTML.
 201 @var{comment} supports the same substitution variables as
 202 @option{--set-label}, plus
 203
 204
 205 @end table
 206
 207 @table @option
 208 @item -O format=@var{format}
 209 Overrides the format inferred from the output file's extension.  Use
 210 @option{--help} to list the available formats.  @xref{Invoking PSPP},
 211 for details of the available output formats.
 212
 213 @item -O @var{option}=@var{value}
 214 Sets an option for the output file format.  @xref{Invoking PSPP}, for
 215 details of the available output options.
 216
 217 @item -F
 218 @itemx --force
 219 By default, if the source is corrupt or otherwise cannot be processed,
 220 the destination is not written.  With @option{-F} or @option{--force},
 221 the destination is written as best it can, even with errors.
 222 @end table
 223
 224 @node The pspp-output get-table-look Command
 225 @section The @code{get-table-look} Command
 226
 227 @display
 228 @t{pspp-output} [@var{options}] @t{get-table-look} @var{source} @var{destination}
 229 @end display
 230
 231 Reads SPV file @var{source}, applies any selection options
 232 (@pxref{Input Selection Options}), picks the first table from the
 233 selected object, extracts the TableLook from that table, and writes it
 234 to @var{destination} (typically with an @file{.stt} extension) in the
 235 TableLook XML format.
 236
 237 The user may use the TableLook file to change the style of tables in
 238 other files, by passing it to the @option{--table-look} option on the
 239 @code{convert} command.
 240
 241 @node The pspp-output convert-table-look Command
 242 @section The @code{convert-table-look} Command
 243
 244 @display
 245 @t{pspp-output} [@var{options}] @t{convert-table-look} @var{source} @var{destination}
 246 @end display
 247
 248 Reads @file{.stt} or @file{.tlo} file @var{source}, and writes it back
 249 to @var{destination} (typically with an @file{.stt} extension) in the
 250 TableLook XML format.  This is useful for converting a TableLook
 251 @file{.tlo} file from SPSS 15 or earlier into the newer @file{.stt}
 252 format.
 253
 254 @node Input Selection Options
 255 @section Input Selection Options
 256
 257 The @command{dir} and @command{convert} commands, by default, operate
 258 on all of the objects in the source SPV file, except for objects that
 259 are not visible in the output viewer window.  The user may specify
 260 these options to select a subset of the input objects.  When multiple
 261 options are used, only objects that satisfy all of them are selected:
 262
 263 @table @option
 264 @item --select=@r{[}^@r{]}@var{class}@dots{}
 265 Include only objects of the given @var{class}; with leading @samp{^},
 266 include only objects not in the class.  Use commas to separate
 267 multiple classes.  The supported classes are:
 268
 269 @quotation
 270 @code{charts headings logs models tables texts trees warnings
 271 outlineheaders pagetitle notes unknown other}
 272 @end quotation
 273
 274 Use @option{--select=help} to print this list of classes.
 275
 276 @item --commands=@r{[}^@r{]}@var{command}@dots{}
 277 @itemx --subtypes=@r{[}^@r{]}@var{subtype}@dots{}
 278 @itemx --labels=@r{[}^@r{]}@var{label}@dots{}
 279 Include only objects with the specified @var{command}, @var{subtype},
 280 or @var{label}.  With a leading @samp{^}, include only the objects
 281 that do not match.  Multiple values may be specified separated by
 282 commas.  An asterisk at the end of a value acts as a wildcard.
 283
 284 The @option{--command} option matches command identifiers, case
 285 insensitively.  All of the objects produced by a single command use
 286 the same, unique command identifier.  Command identifiers are always
 287 in English regardless of the language used for output.  They often
 288 differ from the command name in PSPP syntax.  Use the
 289 @command{pspp-output} program's @command{dir} command to print command
 290 identifiers in particular output.
 291
 292 The @option{--subtypes} option matches particular tables within a
 293 command, case insensitively.  Subtypes are not necessarily unique: two
 294 commands that produce similar output tables may use the same subtype.
 295 Subtypes are always in English and @command{dir} will print them.
 296
 297 The @option{--labels} option matches the labels in table output (that
 298 is, the table titles).  Labels are affected by the output language,
 299 variable names and labels, split file settings, and other factors.
 300
 301 @item --nth-commands=@var{n}@dots{}
 302 Include only objects from the @var{n}th command that matches
 303 @option{--command} (or the @var{n}th command overall if
 304 @option{--command} is not specified), where @var{n} is 1 for the first
 305 command, 2 for the second, and so on.
 306
 307 @item --instances=@var{instance}@dots{}
 308 Include the specified @var{instance} of an object that matches the
 309 other criteria within a single command.  The @var{instance} may be a
 310 number (1 for the first instance, 2 for the second, and so on) or
 311 @code{last} for the last instance.
 312
 313 @item --show-hidden
 314 Include hidden output objects in the output.  By default, they are
 315 excluded.
 316
 317 @item --or
 318 Separates two sets of selection options.  Objects selected by either
 319 set of options are included in the output.
 320 @end table
 321
 322 The following additional input selection options are intended mainly
 323 for use by PSPP developers:
 324
 325 @table @option
 326 @item --errors
 327 Include only objects that cause an error when read.  With the
 328 @command{convert} command, this is most useful in conjunction with the
 329 @option{--force} option.
 330
 331 @item --members=@var{member}@dots{}
 332 Include only the objects that include a listed Zip file @var{member}.
 333 More than one name may be included, comma-separated.  The members in
 334 an SPV file may be listed with the @command{dir} command by adding the
 335 @option{--show-members} option or with the @command{zipinfo} program
 336 included with many operating systems.  Error messages that
 337 @command{pspp-output} prints when it reads SPV files also often
 338 include member names.
 339
 340 @item --member-names
 341 Displays the name of the Zip member or members associated with each
 342 object just above the object itself.
 343 @end table