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