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

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