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