pintos-os.org Git - pspp/blob - utilities/pspp-output.1

   1 .\" -*- nroff -*-
   2 .de IQ
   3 .  br
   4 .  ns
   5 .  IP "\\$1"
   6 ..
   7 .TH pspp\-output 1 "December 2019" "PSPP" "PSPP Manual"
   8 .
   9 .SH NAME
  10 pspp\-output \- convert and operate on SPSS viewer (SPV) files
  11 .
  12 .SH SYNOPSIS
  13 \fBpspp\-output detect \fIfile\fR
  14 .br
  15 \fBpspp\-output \fR[\fIoptions\fR] \fBdir\fR \fIfile\fR
  16 .br
  17 \fBpspp\-output \fR[\fIoptions\fR] \fBconvert\fR \fIsource destination\fR
  18 .br
  19 \fBpspp\-output \fR[\fIoptions\fR] \fBget\-table\-look\fR \fIsource destination\fR
  20 .br
  21 \fBpspp\-output \fR[\fIoptions\fR] \fBconvert\-table\-look\fR \fIsource destination\fR
  22 .br
  23 \fBpspp\-output \-\-help\fR | \fB\-h\fR
  24 .br
  25 \fBpspp\-output \-\-version\fR | \fB\-v\fR
  26 .
  27 .SH DESCRIPTION
  28 .PP
  29 \fBpspp\-output\fR is a command-line utility accompanying PSPP.
  30 It supports multiple operations on SPSS viewer or \fB.spv\fR files,
  31 here called SPV files.  SPSS 16 and later writes SPV files to
  32 represent the contents of its output editor.
  33 .PP
  34 SPSS 15 and earlier versions instead use \fB.spo\fR files.
  35 \fBpspp\-output\fR does not support this format.
  36 .PP
  37 \fBpspp\-output\fR has a number of subcommands, documented separately
  38 below.  \fBpspp\-output\fR also has several undocumented command forms
  39 that developers may find useful for debugging.
  40 .
  41 .SS The \fBdetect\fR command
  42 When invoked as \fBpspp\-output detect \fIfile\fR, \fBpspp\-output\fR
  43 reads enough of \fIfile\fR to determine whether it is an SPV file.  If
  44 so, it exits successfully without outputting anything.  When
  45 \fIfile\fR is not an SPV file or if some other error occurs,
  46 \fBpspp\-output\fR prints an error message and exits with a failure
  47 indication.
  48 .
  49 .SS The \fBdir\fR command
  50 When invoked as \fBpspp\-output dir \fIfile\fR, \fBpspp\-output\fR
  51 prints on stdout a table of contents for SPV file \fIfile\fR.  By
  52 default, this table lists every object in the file, except for hidden
  53 objects.  See the \fBInput Selection Options\fR section below for
  54 information on the options available to select a subset of objects.
  55 .PP
  56 The following additional option for \fBdir\fR is intended mainly for
  57 use by PSPP developers:
  58 .
  59 .IP "\fB\-\-member\-names\fR"
  60 Also show the names of the Zip members associated with each object.
  61 .
  62 .SS The \fBconvert\fR command
  63 When invoked as \fBpspp\-output convert \fIsource destination\fR,
  64 \fBpspp\-output\fR reads the SPV file \fIsource\fR and converts it
  65 to another format, writing the output to \fIdestination\fR.
  66 .PP
  67 By default, \fBpspp\-output\fR infers the intended format for
  68 \fIdestination\fR from its extension.  The known extensions are
  69 generally: \fBcsv html list odt pdf ps spv svg txt\fR.  Use
  70 \fB\-\-help\fR to see an accurate list, since a given installation
  71 might be built without support for some formats.
  72 .PP
  73 See the \fBInput Selection Options\fR section below for information on
  74 the options available to select a subset of objects to include in the
  75 output.  The following additional options are accepted:
  76 .IP "\fB-O format=\fIformat\fR"
  77 Overrides the format inferred from the output file's extension.
  78 \fIformat\fR must be one of the extensions listed above.
  79 .IP "\fB-O \fIoption\fB=\fIvalue\fR"
  80 Sets an option for the output file format.  Refer to the PSPP manual
  81 for details of the available output options.
  82 .IP \fB\-F\fR
  83 .IQ \fB\-\-force\fR
  84 By default, if the source is corrupt or otherwise cannot be processed,
  85 the destination is not written.  These option make \fBpspp\-output\fR
  86 write the output as best it can, even with errors.
  87 .IP \fB\-\-table\-look=\fIfile\fR
  88 Reads a table style from \fIfile\fR and applies it to all of the
  89 output tables.  The file should a TableLook \fB.stt\fR or \fB.tlo\fR
  90 file.
  91 .SS The \fBget\-table\-look\fR command
  92 When invoked as \fBpspp\-output get\-table\-look \fIsource
  93 destination\fR, \fBpspp\-output\fR reads SPV file \fIsource\fR,
  94 applies any selection options (as described under \fBInput Selection
  95 Options\fR below), picks the first table from the selected object,
  96 extracts the TableLook from that table, and writes it to
  97 \fIdestination\fR (typically with an \fB.stt\fR extension) in the
  98 TableLook XML format.
  99 .PP
 100 The user may use the TableLook file to change the style of tables in
 101 other files, by passing it to the \fB\-\-table\-look\fR option on the
 102 \fBconvert\fR command.
 103 .SS The \fBconvert\-table\-look\fR command
 104 When invoked as \fBpspp\-output convert\-table\-look \fIsource
 105 destination\fR, \fBpspp\-output\fR reads \fB.stt\fR or \fR.tlo\fR file
 106 \fIsource\fR, and writes it back to \fIdestination\fR (typically with
 107 an \fB.stt\fR extension) in the TableLook XML format.  This is useful
 108 for converting a TableLook \fB.tlo\fR file from SPSS 15 or earlier
 109 into the newer \fB.stt\fR format.
 110 .SS "Input Selection Options"
 111 The \fBdir\fR and \fBconvert\fR commands, by default, operate on all
 112 of the objects in the source SPV file, except for objects that are not
 113 visible in the output viewer window.  The user may specify these
 114 options to select a subset of the input objects.  When multiple
 115 options are used, only objects that satisfy all of them are selected:
 116 .IP "\fB\-\-select=\fR[\fB^\fR]\fIclass\fR..."
 117 Include only objects of the given \fIclass\fR; with leading \fB^\fR,
 118 include only objects not in the class.  Use commas to separate
 119 multiple classes.  The supported classes are:
 120 .RS
 121 .IP
 122 \fBcharts headings logs models tables texts trees warnings
 123 outlineheaders pagetitle notes unknown other\fR
 124 .RE
 125 .IP
 126 Use \fB\-\-select=help\fR to print this list of classes.
 127 .IP "\-\-commands=\fR[\fB^\fR]\fIcommand\fR..."
 128 .IQ "\-\-subtypes=\fR[\fB^\fR]\fIsubtype\fR..."
 129 .IQ "\-\-labels=\fR[\fB^\fR]\fIlabel\fR..."
 130 Include only objects with the specified \fIcommand\fR, \fIsubtype\fR,
 131 or \fIlabel\fR.  With a leading \fB^\fR, include only the objects
 132 that do not match.  Multiple values may be specified separated by
 133 commas.  An asterisk at the end of a value acts as a wildcard.
 134 .IP
 135 The \fB\-\-command\fR option matches command identifiers, case
 136 insensitively.  All of the objects produced by a single command use
 137 the same, unique command identifier.  Command identifiers are always
 138 in English regardless of the language used for output.  They often
 139 differ from the command name in PSPP syntax.  Use the
 140 \fBpspp\-output\fR program's \fBdir\fR command to print command
 141 identifiers in particular output.
 142 .IP
 143 The \fB\-\-subtypes\fR option matches particular tables within a
 144 command, case insensitively.  Subtypes are not necessarily unique: two
 145 commands that produce similar output tables may use the same subtype.
 146 Subtypes are always in English and \fBdir\fR will print them.
 147 .IP
 148 The \fB\-\-labels\fR option matches the labels in table output (that
 149 is, the table titles).  Labels are affected by the output language,
 150 variable names and labels, split file settings, and other factors.
 151 .IP "\-\-nth-commands=\fIn\fR..."
 152 Include only objects from the \fIn\fRth command that matches
 153 \fB\-\-commands\fR (or the \fIn\fRth command overall if
 154 \fB\-\-commands\fR is not specified), where \fIn\fR is 1 for the first
 155 command, 2 for the second, and so on.
 156 .IP "\fB\-\-instances=\fIinstance\fR..."
 157 Include the specified \fIinstance\fR of an object that matches the
 158 other criteria within a single command.  The \fIinstance\fR may be a
 159 number (1 for the first instance, 2 for the second, and so on) or
 160 \fBlast\fR for the last instance.
 161 .IP "\fB\-\-show\-hidden"
 162 Include hidden output objects in the output.  By default, they are
 163 excluded.
 164 .IP "\fB\-\-or\fR"
 165 Separates two sets of selection options.  Objects selected by either
 166 set of options are included in the output.
 167 .PP
 168 The following additional input selection options are intended mainly
 169 for use by PSPP developers:
 170 .IP "\fB\-\-errors\fR"
 171 Include only objects that cause an error when read.  With the
 172 \fBconvert\fR command, this is most useful in conjunction with the
 173 \fB\-\-force\fR option.
 174 .IP "\fB\-\-members=\fImember\fR..."
 175 Include only the objects that include a listed Zip file \fImember\fR.
 176 More than one name may be included, comma-separated.  The members in
 177 an SPV file may be listed with the \fBdir\fR command by adding the
 178 \fB\-\-show\-members\fR option or with the \fBzipinfo\fR program
 179 included with many operating systems.  Error messages that
 180 \fBpspp\-output\fR prints when it reads SPV files also often include
 181 member names.
 182 .IP "\fB\-\-member\-names\fR"
 183 Displays the name of the Zip member or members associated with each
 184 object just above the object itself.
 185 .SH "OPTIONS"
 186 .IP "\fB\-h\fR"
 187 .IQ "\fB\-\-help\fR"
 188 Prints a usage message on stdout and exits.
 189 .
 190 .IP "\fB\-v\fR"
 191 .IQ "\fB\-\-version\fR"
 192 Prints version information on stdout and exits.
 193 .
 194 .SH "AUTHORS"
 195 Ben Pfaff.
 196 .
 197 .SH "SEE ALSO"
 198 .
 199 .BR pspp\-convert (1),
 200 .BR pspp (1),
 201 .BR psppire (1).