doc/invoking.texi

   1 @node Invoking PSPP
   2 @chapter Invoking @command{pspp}
   3 @cindex invocation
   4 @cindex PSPP, invoking
   5
   6 PSPP has two separate user interfaces.  This chapter describes
   7 @command{pspp}, PSPP's command-line driven text-based user interface.
   8 The following chapter briefly describes PSPPIRE, the graphical user
   9 interface to PSPP.
  10
  11 The sections below describe the @command{pspp} program's command-line
  12 interface.
  13
  14 @menu
  15 * Main Options::
  16 * PDF PostScript and SVG Output Options::
  17 * Plain Text Output Options::
  18 * HTML Output Options::
  19 * OpenDocument Output Options::
  20 * Comma-Separated Value Output Options::
  21 @end menu
  22
  23 @node Main Options
  24 @section Main Options
  25
  26 Here is a summary of all the options, grouped by type, followed by
  27 explanations in the same order.
  28
  29 In the table, arguments to long options also apply to any
  30 corresponding short options.
  31
  32 @table @emph
  33 @item Non-option arguments
  34 @example
  35 @var{syntax-file}
  36 @end example
  37
  38 @item Output options
  39 @example
  40 -o, --output=@var{output-file}
  41 -O @var{option}=@var{value}
  42 -O format=@var{format}
  43 -O device=@{terminal|listing@}
  44 --no-output
  45 -e, --error-file=@var{error-file}
  46 @end example
  47
  48 @item Language options
  49 @example
  50 -I, --include=@var{dir}
  51 -I-, --no-include
  52 -i, --interactive
  53 -r, --no-statrc
  54 -a, --algorithm=@{compatible|enhanced@}
  55 -x, --syntax=@{compatible|enhanced@}
  56 @end example
  57
  58 @item Informational options
  59 @example
  60 -h, --help
  61 -V, --version
  62 @end example
  63
  64 @item Other options
  65 @example
  66 -s, --safer
  67 --testing-mode
  68 @end example
  69 @end table
  70
  71 @table @code
  72 @item @var{syntax-file}
  73 Read and execute the named syntax file.  If no syntax files are
  74 specified, PSPP prompts for commands.  If any syntax files are
  75 specified, PSPP by default exits after it runs them, but you may make
  76 it prompt for commands by specifying @samp{-} as an additional syntax
  77 file.
  78
  79 @item -o @var{output-file}
  80 Write output to @var{output-file}.  PSPP has several different output
  81 drivers that support output in various formats (use @option{--help} to
  82 list the available formats).  Specify this option more than once to
  83 produce multiple output files, presumably in different formats.
  84
  85 Use @samp{-} as @var{output-file} to write output to standard output.
  86
  87 If no @option{-o} option is used, then PSPP writes output to standard
  88 output in plain text format.
  89
  90 @item -O @var{option}=@var{value}
  91 Sets an option for the output file configured by a preceding
  92 @option{-o}.  Most options are specific to particular output formats.
  93 A few options that apply generically are listed below.
  94
  95 @item -O format=@var{format}
  96 PSPP uses the extension of the file name given on @option{-o} to
  97 select an output format.  Use this option to override this choice by
  98 specifying an alternate format, e.g.@: @option{-o pspp.out -O html} to
  99 write HTML to a file named @file{pspp.out}.  Use @option{--help} to
 100 list the available formats.
 101
 102 @item -O device=@{terminal|listing@}
 103 Sets whether PSPP considers the output device configured by the
 104 preceding @option{-o} to be a terminal or a listing device.  This
 105 affects what output will be sent to the device, as configured by the
 106 SET command's output routing subcommands (@pxref{SET}).  By default,
 107 output written to standard output is considered a terminal device and
 108 other output is considered a listing device.
 109
 110 @item --no-output
 111 Disables output entirely, if neither @option{-o} nor @option{-O} is
 112 also used.  If one of those options is used, @option{--no-output} has
 113 no effect.
 114
 115 @item -e @var{error-file}
 116 @itemx --error-file=@var{error-file}
 117 Configures a file to receive PSPP error, warning, and note messages in
 118 plain text format.  Use @samp{-} as @var{error-file} to write messages
 119 to standard output.  The default error file is standard output in the
 120 absence of these options, but this is suppressed if an output device
 121 writes to standard output (or another terminal), to avoid printing
 122 every message twice.  Use @samp{none} as @var{error-file} to
 123 explicitly suppress the default.
 124
 125 @item -I @var{dir}
 126 @itemx --include=@var{dir}
 127 Appends @var{dir} to the set of directories searched by INCLUDE
 128 (@pxref{INCLUDE}) and INSERT (@pxref{INSERT}).
 129
 130 @item -I-
 131 @itemx --no-include
 132 Clears all directories from the include path, including directories
 133 inserted in the include path by default.  The default include path is
 134 @file{.} (the current directory), followed by @file{.pspp} in the
 135 user's home directory, followed by PSPP's system configuration
 136 directory (usually @file{/etc/pspp} or @file{/usr/local/etc/pspp}).
 137
 138 @item -i
 139 @itemx --interactive
 140 This option forces syntax files to be interpreted in interactive
 141 mode, rather than the default batch mode.  @xref{Syntax Variants}, for
 142 a description of the differences.
 143
 144 @item -r
 145 @itemx --no-statrc
 146 Disables running @file{rc} at PSPP startup time.
 147
 148 @item -a @{enhanced|compatible@}
 149 @itemx --algorithm=@{enhanced|compatible@}
 150 With @code{enhanced}, the default, PSPP uses the best implemented
 151 algorithms for statistical procedures.  With @code{compatible},
 152 however, PSPP will in some cases use inferior algorithms to produce
 153 the same results as the proprietary program SPSS.
 154
 155 Some commands have subcommands that override this setting on a per
 156 command basis.
 157
 158 @item -x @{enhanced|compatible@}
 159 @itemx --syntax=@{enhanced|compatible@}
 160 With @code{enhanced}, the default, PSPP accepts its own extensions
 161 beyond those compatible with the proprietary program SPSS.  With
 162 @code{compatible}, PSPP rejects syntax that uses these extensions.
 163
 164 @item -?
 165 @itemx --help
 166 Prints a message describing PSPP command-line syntax and the available
 167 device formats, then exits.
 168
 169 @item -V
 170 @itemx --version
 171 Prints a brief message listing PSPP's version, warranties you don't
 172 have, copying conditions and copyright, and e-mail address for bug
 173 reports, then exits.
 174
 175 @item -s
 176 @itemx --safer
 177 Disables certain unsafe operations.  This includes the ERASE and
 178 HOST commands, as well as use of pipes as input and output files.
 179
 180 @item --testing-mode
 181 Invoke heuristics to assist with testing PSPP.  For use by @code{make
 182 check} and similar scripts.
 183 @end table
 184
 185 @node PDF PostScript and SVG Output Options
 186 @section PDF, PostScript, and SVG Output Options
 187
 188 To produce output in PDF, PostScript, and SVG formats, specify
 189 @option{-o @var{file}} on the PSPP command line, optionally followed
 190 by any of the options shown in the table below to customize the output
 191 format.
 192
 193 PDF, PostScript, and SVG output is only available if your installation
 194 of PSPP was compiled with the Cairo library.
 195
 196 @table @code
 197 @item -O format=@{pdf|ps|svg@}
 198 Specify the output format.  This is only necessary if the file name
 199 given on @option{-o} does not end in @file{.pdf}, @file{.ps}, or
 200 @file{.svg}.
 201
 202 @item -O paper-size=@var{paper-size}
 203 Paper size, as a name (e.g.@: @code{a4}, @code{letter}) or
 204 measurements (e.g.@: @code{210x297}, @code{8.5x11in}).
 205
 206 The default paper size is taken from the @env{PAPERSIZE} environment
 207 variable or the file indicated by the @env{PAPERCONF} environment
 208 variable, if either variable is set.  If not, and your system supports
 209 the @code{LC_PAPER} locale category, then the default paper size is
 210 taken from the locale.  Otherwise, if @file{/etc/papersize} exists,
 211 the default paper size is read from it.  As a last resort, A4 paper is
 212 assumed.
 213
 214 @item -O orientation=@var{orientation}
 215 Either @code{portrait} or @code{landscape}.  Default: @code{portrait}.
 216
 217 @item -O headers=@var{boolean}
 218 When enabled, headers showing the time and date, title and subtitle,
 219 and page number are printed at the top of each page.  Default:
 220 @code{on}.
 221
 222 @item -O left-margin=@var{dimension}
 223 @itemx -O right-margin=@var{dimension}
 224 @itemx -O top-margin=@var{dimension}
 225 @itemx -O bottom-margin=@var{dimension}
 226 Sets the margins around the page.  The headers, if enabled, are not
 227 included in the margins; they are in addition to the margins.  See
 228 below for the allowed forms of @var{dimension} Default: @code{0.5in}.
 229
 230 @item -O prop-font=@var{font-name}
 231 @itemx -O emph-font=@var{font-name}
 232 @itemx -O fixed-font=@var{font-name}
 233 Sets the font used for proportional, emphasized, or fixed-pitch text.
 234 Most systems support CSS-like font names such as ``serif'' and
 235 ``monospace'', but a wide range of system-specific font are likely to
 236 be supported as well.
 237
 238 Default: proportional font @code{serif}, emphasis font @code{serif
 239 italic}, fixed-pitch font @code{monospace}.
 240
 241 @item -O font-size=@var{font-size}
 242 Sets the size of the default fonts, in thousandths of a point.  Default:
 243 10000 (10 point).
 244
 245 @item -O line-gutter=@var{dimension}
 246 Sets the width of white space on either side of lines that border text
 247 or graphics objects.  Default: @code{1pt}.
 248
 249 @item -O line-spacing=@var{dimension}
 250 Sets the spacing between the lines in a double line in a table.
 251 Default: @code{1pt}.
 252
 253 @item -O line-width=@var{dimension}
 254 Sets the width of the lines used in tables.  Default: @code{0.5pt}.
 255 @end table
 256
 257 Each @var{dimension} value above may be specified in various units
 258 based on its suffix: @samp{mm} for millimeters, @samp{in} for inches,
 259 or @samp{pt} for points.  Lacking a suffix, numbers below 50 are
 260 assumed to be in inches and those about 50 are assumed to be in
 261 millimeters.
 262
 263 @node Plain Text Output Options
 264 @section Plain Text Output Options
 265
 266 PSPP can produce plain text output, drawing boxes using ASCII or
 267 Unicode line drawing characters.  To produce plain text output,
 268 specify @option{-o @var{file}} on the PSPP command line, optionally
 269 followed by options from the table below to customize the output
 270 format.
 271
 272 @table @code
 273 @item -O format=txt
 274 Specify the output format.  This is only necessary if the file name
 275 given on @option{-o} does not end in @file{.txt} or @file{.list}.
 276
 277 @item -O charts=@{@var{template}.png|none@}
 278 Name for chart files included in output.  The value should be a file
 279 name that includes a single @samp{#} and ends in @file{png}.  When a
 280 chart is output, the @samp{#} is replaced by the chart number.  The
 281 default is the file name specified on @option{-o} with the extension
 282 stripped off and replaced by @file{-#.png}.
 283
 284 Specify @code{none} to disable chart output.  Charts are always
 285 disabled if your installation of PSPP was compiled without the
 286 Cairo library.
 287
 288 @item -O paginate=@var{boolean}
 289 If set, PSPP writes an ASCII formfeed the end of every page.  Default:
 290 @code{off}.
 291
 292 @item -O headers=@var{boolean}
 293 If enabled, PSPP prints two lines of header information giving title
 294 and subtitle, page number, date and time, and PSPP version are printed
 295 at the top of every page.  These two lines are in addition to any top
 296 margin requested.  Default: @code{off}.
 297
 298 @item -O length=@var{line-count}
 299 Physical length of a page.  Headers and margins are subtracted from
 300 this value.  You may specify the number of lines as a number, or for
 301 screen output you may specify @code{auto} to track the height of the
 302 terminal as it changes.  Default: @code{66}.
 303
 304 @item -O width=@var{character-count}
 305 Width of a page, in characters.  Margins are subtracted from this
 306 value.  For screen output you may specify @code{auto} in place of a
 307 number to track the width of the terminal as it changes.  Default:
 308 @code{79}.
 309
 310 @item -O top-margin=@var{top-margin-lines}
 311 Length of the top margin, in lines.  PSPP subtracts this value from
 312 the page length.  Default: @code{0}.
 313
 314 @item -O bottom-margin=@var{bottom-margin-lines}
 315 Length of the bottom margin, in lines.  PSPP subtracts this value from
 316 the page length.  Default: @code{0}.
 317
 318 @item -O box[@var{line-type}]=@var{box-chars}
 319 Sets the characters used for lines in tables.  @var{line-type} is a
 320 4-digit number that indicates the type of line to change, in the order
 321 `right', `bottom', `left', `top'.  Each digit is 0 for ``no line'', 1
 322 for a single line, and 2 for a double line.  @var{box-chars} is the
 323 character or string of characters to use for this type of line.
 324
 325 For example, @code{box[0101]="|"} sets @samp{|} as the character to
 326 use for a single-width vertical line, and @code{box[1100]="\xda"} sets
 327 @samp{"\xda"}, which on MS-DOS is suitable for the top-left corner of
 328 a box, as the character for the intersection of two single-width
 329 lines, one each from the right and bottom.
 330
 331 The defaults use @samp{-}, @samp{|}, and @samp{+} for single-width
 332 lines and @samp{=} and @samp{#} for double-width lines.
 333
 334 @item -O init=@var{init-string}
 335 If set, this string is written at the beginning of each output file.
 336 It can be used to initialize device features, e.g.@: to enable VT100
 337 line-drawing characters.
 338
 339 @item -O emphasis=@{none|bold|underline@}
 340 How to emphasize text.  Bold and underline emphasis are achieved with
 341 overstriking, which may not be supported by all the software to which
 342 you might pass the output.  Default: @code{none}.
 343 @end table
 344
 345 @node HTML Output Options
 346 @section HTML Output Options
 347
 348 To produce output in HTML format, specify @option{-o @var{file}} on
 349 the PSPP command line, optionally followed by any of the options shown
 350 in the table below to customize the output format.
 351
 352 @table @code
 353 @item -O format=html
 354 Specify the output format.  This is only necessary if the file name
 355 given on @option{-o} does not end in @file{.html}.
 356
 357 @item -O charts=@{@var{template}.png|none@}
 358 Sets the name used for chart files.  @xref{Plain Text Output Options},
 359 for details.
 360 @end table
 361
 362 @node OpenDocument Output Options
 363 @section OpenDocument Output Options
 364
 365 To produce output as an OpenDocument text (ODT) document, specify
 366 @option{-o @var{file}} on the PSPP command line.  If @var{file} does
 367 not end in @file{.odt}, you must also specify @option{-O format=odt}.
 368
 369 ODT support is only available if your installation of PSPP was
 370 compiled with the libxml2 library.
 371
 372 The OpenDocument output format does not have any configurable options.
 373
 374 @node Comma-Separated Value Output Options
 375 @section Comma-Separated Value Output Options
 376
 377 To produce output in comma-separated value (CSV) format, specify
 378 @option{-o @var{file}} on the PSPP command line, optionally followed
 379 by any of the options shown in the table below to customize the output
 380 format.
 381
 382 @table @code
 383 @item -O format=csv
 384 Specify the output format.  This is only necessary if the file name
 385 given on @option{-o} does not end in @file{.csv}.
 386
 387 @item -O separator=@var{field-separator}
 388 Sets the character used to separate fields.  The default is a comma
 389 (@samp{,}).
 390 @end table
 391
 392 The CSV format used is an extension to that specified in RFC 4180:
 393
 394 @table @asis
 395 @item Tables
 396 Each table row is output on a separate line, and each column is output
 397 as a field.  The contents of a cell that spans multiple rows or
 398 columns is output only for the top-left row and column; the rest are
 399 output as empty fields.  When a table has a caption, it is output just
 400 above the table as a single field prefixed by @samp{Table:}.
 401
 402 @item Text
 403 Text in output is printed as a field on a line by itself.  The TITLE
 404 and SUBTITLE produce similar output, prefixed by @samp{Title:} or
 405 @samp{Subtitle:}, respectively.
 406
 407 @item Messages
 408 Errors, warnings, and notes are printed the same way as text.
 409
 410 @item Charts
 411 Charts are not included in CSV output.
 412 @end table
 413
 414 Successive output items are separated by a blank line.
 415
 416 @node Invoking PSPPIRE
 417 @chapter Invoking @command{psppire}
 418 @section The graphic user interface
 419 @cindex Graphic user interface
 420 @cindex PSPPIRE
 421
 422 The PSPPIRE graphic user interface for PSPP can perform all
 423 functionality of the command line interface.  In addition it gives an
 424 instantaneous view of the data, variables and statistical output.
 425
 426 The graphic user interface can be started by typing @command{psppire} at a
 427 command prompt.
 428 Alternatively many systems have a system of interactive menus or buttons
 429 from which @command{psppire} can be started by a series of mouse clicks.
 430
 431 Once the principles of the PSPP system are understood,
 432 the graphic user interface is designed to be largely intuitive, and
 433 for this reason is covered only very briefly by this manual.