doc/invoking.texi

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