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 left-margin=@var{dimension}
 218 @itemx -O right-margin=@var{dimension}
 219 @itemx -O top-margin=@var{dimension}
 220 @itemx -O bottom-margin=@var{dimension}
 221 Sets the margins around the page.  See
 222 below for the allowed forms of @var{dimension} Default: @code{0.5in}.
 223
 224 @item -O prop-font=@var{font-name}
 225 @itemx -O emph-font=@var{font-name}
 226 @itemx -O fixed-font=@var{font-name}
 227 Sets the font used for proportional, emphasized, or fixed-pitch text.
 228 Most systems support CSS-like font names such as ``serif'' and
 229 ``monospace'', but a wide range of system-specific font are likely to
 230 be supported as well.
 231
 232 Default: proportional font @code{serif}, emphasis font @code{serif
 233 italic}, fixed-pitch font @code{monospace}.
 234
 235 @item -O font-size=@var{font-size}
 236 Sets the size of the default fonts, in thousandths of a point.  Default:
 237 10000 (10 point).
 238
 239 @item -O line-gutter=@var{dimension}
 240 Sets the width of white space on either side of lines that border text
 241 or graphics objects.  Default: @code{1pt}.
 242
 243 @item -O line-spacing=@var{dimension}
 244 Sets the spacing between the lines in a double line in a table.
 245 Default: @code{1pt}.
 246
 247 @item -O line-width=@var{dimension}
 248 Sets the width of the lines used in tables.  Default: @code{0.5pt}.
 249 @end table
 250
 251 Each @var{dimension} value above may be specified in various units
 252 based on its suffix: @samp{mm} for millimeters, @samp{in} for inches,
 253 or @samp{pt} for points.  Lacking a suffix, numbers below 50 are
 254 assumed to be in inches and those about 50 are assumed to be in
 255 millimeters.
 256
 257 @node Plain Text Output Options
 258 @section Plain Text Output Options
 259
 260 PSPP can produce plain text output, drawing boxes using ASCII or
 261 Unicode line drawing characters.  To produce plain text output,
 262 specify @option{-o @var{file}} on the PSPP command line, optionally
 263 followed by options from the table below to customize the output
 264 format.
 265
 266 @table @code
 267 @item -O format=txt
 268 Specify the output format.  This is only necessary if the file name
 269 given on @option{-o} does not end in @file{.txt} or @file{.list}.
 270
 271 @item -O charts=@{@var{template}.png|none@}
 272 Name for chart files included in output.  The value should be a file
 273 name that includes a single @samp{#} and ends in @file{png}.  When a
 274 chart is output, the @samp{#} is replaced by the chart number.  The
 275 default is the file name specified on @option{-o} with the extension
 276 stripped off and replaced by @file{-#.png}.
 277
 278 Specify @code{none} to disable chart output.  Charts are always
 279 disabled if your installation of PSPP was compiled without the
 280 Cairo library.
 281
 282 @item -O paginate=@var{boolean}
 283 If set, PSPP writes an ASCII formfeed the end of every page.  Default:
 284 @code{off}.
 285
 286 @item -O headers=@var{boolean}
 287 If enabled, PSPP prints two lines of header information giving title
 288 and subtitle, page number, date and time, and PSPP version are printed
 289 at the top of every page.  These two lines are in addition to any top
 290 margin requested.  Default: @code{off}.
 291
 292 @item -O length=@var{line-count}
 293 Physical length of a page.  Headers and margins are subtracted from
 294 this value.  You may specify the number of lines as a number, or for
 295 screen output you may specify @code{auto} to track the height of the
 296 terminal as it changes.  Default: @code{66}.
 297
 298 @item -O width=@var{character-count}
 299 Width of a page, in characters.  Margins are subtracted from this
 300 value.  For screen output you may specify @code{auto} in place of a
 301 number to track the width of the terminal as it changes.  Default:
 302 @code{79}.
 303
 304 @item -O top-margin=@var{top-margin-lines}
 305 Length of the top margin, in lines.  PSPP subtracts this value from
 306 the page length.  Default: @code{0}.
 307
 308 @item -O bottom-margin=@var{bottom-margin-lines}
 309 Length of the bottom margin, in lines.  PSPP subtracts this value from
 310 the page length.  Default: @code{0}.
 311
 312 @item -O box[@var{line-type}]=@var{box-chars}
 313 Sets the characters used for lines in tables.  @var{line-type} is a
 314 4-digit number that indicates the type of line to change, in the order
 315 `right', `bottom', `left', `top'.  Each digit is 0 for ``no line'', 1
 316 for a single line, and 2 for a double line.  @var{box-chars} is the
 317 character or string of characters to use for this type of line.
 318
 319 For example, @code{box[0101]="|"} sets @samp{|} as the character to
 320 use for a single-width vertical line, and @code{box[1100]="\xda"} sets
 321 @samp{"\xda"}, which on MS-DOS is suitable for the top-left corner of
 322 a box, as the character for the intersection of two single-width
 323 lines, one each from the right and bottom.
 324
 325 The defaults use @samp{-}, @samp{|}, and @samp{+} for single-width
 326 lines and @samp{=} and @samp{#} for double-width lines.
 327
 328 @item -O init=@var{init-string}
 329 If set, this string is written at the beginning of each output file.
 330 It can be used to initialize device features, e.g.@: to enable VT100
 331 line-drawing characters.
 332
 333 @item -O emphasis=@{none|bold|underline@}
 334 How to emphasize text.  Bold and underline emphasis are achieved with
 335 overstriking, which may not be supported by all the software to which
 336 you might pass the output.  Default: @code{none}.
 337 @end table
 338
 339 @node HTML Output Options
 340 @section HTML Output Options
 341
 342 To produce output in HTML format, specify @option{-o @var{file}} on
 343 the PSPP command line, optionally followed by any of the options shown
 344 in the table below to customize the output format.
 345
 346 @table @code
 347 @item -O format=html
 348 Specify the output format.  This is only necessary if the file name
 349 given on @option{-o} does not end in @file{.html}.
 350
 351 @item -O charts=@{@var{template}.png|none@}
 352 Sets the name used for chart files.  @xref{Plain Text Output Options},
 353 for details.
 354 @end table
 355
 356 @node OpenDocument Output Options
 357 @section OpenDocument Output Options
 358
 359 To produce output as an OpenDocument text (ODT) document, specify
 360 @option{-o @var{file}} on the PSPP command line.  If @var{file} does
 361 not end in @file{.odt}, you must also specify @option{-O format=odt}.
 362
 363 ODT support is only available if your installation of PSPP was
 364 compiled with the libxml2 library.
 365
 366 The OpenDocument output format does not have any configurable options.
 367
 368 @node Comma-Separated Value Output Options
 369 @section Comma-Separated Value Output Options
 370
 371 To produce output in comma-separated value (CSV) format, specify
 372 @option{-o @var{file}} on the PSPP command line, optionally followed
 373 by any of the options shown in the table below to customize the output
 374 format.
 375
 376 @table @code
 377 @item -O format=csv
 378 Specify the output format.  This is only necessary if the file name
 379 given on @option{-o} does not end in @file{.csv}.
 380
 381 @item -O separator=@var{field-separator}
 382 Sets the character used to separate fields.  Default: a comma
 383 (@samp{,}).
 384
 385 @item -O quote=@var{qualifier}
 386 Sets @var{qualifier} as the character used to quote fields that
 387 contain white space, the separator (or any of the characters in the
 388 separator, if it contains more than one character), or the quote
 389 character itself.  If @var{qualifier} is longer than one character,
 390 only the first character is used; if @var{qualifier} is the empty
 391 string, then fields are never quoted.
 392
 393 @item -O captions=@var{boolean}
 394 Whether table captions should be printed.  Default: @code{on}.
 395 @end table
 396
 397 The CSV format used is an extension to that specified in RFC 4180:
 398
 399 @table @asis
 400 @item Tables
 401 Each table row is output on a separate line, and each column is output
 402 as a field.  The contents of a cell that spans multiple rows or
 403 columns is output only for the top-left row and column; the rest are
 404 output as empty fields.  When a table has a caption and captions are
 405 enabled, the caption is output just above the table as a single field
 406 prefixed by @samp{Table:}.
 407
 408 @item Text
 409 Text in output is printed as a field on a line by itself.  The TITLE
 410 and SUBTITLE produce similar output, prefixed by @samp{Title:} or
 411 @samp{Subtitle:}, respectively.
 412
 413 @item Messages
 414 Errors, warnings, and notes are printed the same way as text.
 415
 416 @item Charts
 417 Charts are not included in CSV output.
 418 @end table
 419
 420 Successive output items are separated by a blank line.
 421
 422 @node Invoking PSPPIRE
 423 @chapter Invoking @command{psppire}
 424 @section The graphic user interface
 425 @cindex Graphic user interface
 426 @cindex PSPPIRE
 427
 428 The PSPPIRE graphic user interface for PSPP can perform all
 429 functionality of the command line interface.  In addition it gives an
 430 instantaneous view of the data, variables and statistical output.
 431
 432 The graphic user interface can be started by typing @command{psppire} at a
 433 command prompt.
 434 Alternatively many systems have a system of interactive menus or buttons
 435 from which @command{psppire} can be started by a series of mouse clicks.
 436
 437 Once the principles of the PSPP system are understood,
 438 the graphic user interface is designed to be largely intuitive, and
 439 for this reason is covered only very briefly by this manual.