doc/invoking.texi

   1 @node Invocation
   2
   3 @chapter Starting PSPP
   4 @cindex invocation
   5 @cindex PSPP, invoking
   6
   7 There are two separate user interfaces for PSPP.
   8 There is the command line interface, which responds to commands
   9 typed by the user.
  10 The command line interface is generally available on more platforms
  11 than the graphic user interface and since it doesn't require a
  12 graphics device it can be used from a remote terminal.
  13 Platforms which have a windowing system may also be able to support
  14 the graphic user interface.
  15 The graphic user interface can perform all functionality of the
  16 command line interface.
  17 In addition it gives an instantaneous view of the data, variables and
  18 statistical output.
  19
  20 Whichever interface you choose, a basic understanding of the concepts
  21 used by PSPP is necessary before effective use of the system can be achieved.
  22
  23
  24 @menu
  25 * The command line user interface::
  26 * The graphic user interface::
  27 @end menu
  28
  29
  30 @node The command line user interface
  31 @section The command line user interface
  32
  33 @cindex command line, options
  34 @cindex options, command-line
  35
  36 @example
  37 pspp [ -B @var{dir} | --config-dir=@var{dir} ] [ -o @var{device} | --device=@var{device} ]
  38        [ -a @{compatible|enhanced@} | --algorithm=@{compatible|enhanced@}]
  39        [ -x @{compatible|enhanced@} | --syntax=@{compatible|enhanced@}]
  40        [ -I- | --no-include ]
  41        [ -I @var{dir} | --include=@var{dir} ] [ -i | --interactive ]
  42        [ -r | --no-statrc ] [ -h | --help ] [ -l | --list ]
  43        [ -s | --safer ]
  44        [ --testing-mode ] [ -V | --version ] [ -v | --verbose ]
  45        [ @var{key}=@var{value} ] @var{file}@enddots{}
  46 @end example
  47
  48 @menu
  49 * Non-option Arguments::        Specifying syntax files and output devices.
  50 * Configuration Options::       Change the configuration for the current run.
  51 * Input and output options::    Controlling input and output files.
  52 * Language control options::    Language variants.
  53 * Informational options::       Helpful information about PSPP.
  54 @end menu
  55
  56 @node Non-option Arguments
  57 @subsection Non-option Arguments
  58
  59 Syntax files and output device substitutions can be specified on
  60 PSPP's command line:
  61
  62 @table @code
  63 @item @var{file}
  64
  65 A file by itself on the command line will be executed as a syntax file.
  66 If multiple files are specified, they are executed in order, as if
  67 their contents had been given in a single file.
  68 PSPP terminates after the syntax files run, unless the @code{-i} or
  69 @code{--interactive} option is given (@pxref{Language control options}).
  70
  71 @item @var{key}=@var{value}
  72
  73 Defines an output device macro @var{key} to expand to @var{value},
  74 overriding any macro having the same @var{key} defined in the device
  75 configuration file.  @xref{Macro definitions}.
  76
  77 @end table
  78
  79 There is one other way to specify a syntax file, if your operating
  80 system supports it.  If you have a syntax file @file{foobar.stat}, put
  81 the notation
  82
  83 @example
  84 #! /usr/local/bin/pspp
  85 @end example
  86
  87 at the top, and mark the file as executable with @code{chmod +x
  88 foobar.stat}.  (If PSPP is not installed in @file{/usr/local/bin},
  89 then insert its actual installation directory into the syntax file
  90 instead.)  Now you should be able to invoke the syntax file just by
  91 typing its name.  You can include any options on the command line as
  92 usual.  PSPP entirely ignores any lines beginning with @samp{#!}.
  93
  94 @node Configuration Options
  95 @subsection Configuration Options
  96
  97 Configuration options are used to change PSPP's configuration for the
  98 current run.  The configuration options are:
  99
 100 @table @code
 101 @item -a @{compatible|enhanced@}
 102 @itemx --algorithm=@{compatible|enhanced@}
 103
 104 If you chose @code{compatible}, then PSPP will use the same  algorithms
 105 as used by some proprietary statistical analysis packages.
 106 This is not recommended, as  these algorithms are inferior and in some cases
 107 compeletely broken.
 108 The default setting is @code{enhanced}.
 109 Certain commands have subcommands which allow you to override this setting on
 110 a per command basis.
 111
 112 @item -B @var{dir}
 113 @itemx --config-dir=@var{dir}
 114
 115 Sets the configuration directory to @var{dir}.  @xref{File locations}.
 116
 117 @item -o @var{device}
 118 @itemx --device=@var{device}
 119
 120 Selects the output device with name @var{device}.  If this option is
 121 given more than once, then all devices mentioned are selected.  This
 122 option disables all devices besides those mentioned on the command line.
 123 @end table
 124
 125 @node Input and output options
 126 @subsection Input and output options
 127
 128 Input and output options affect how PSPP reads input and writes
 129 output.  These are the input and output options:
 130
 131 @table @code
 132 @item -I-
 133 @itemx --no-include
 134
 135 Clears all directories from the include path.  This includes all
 136 directories put in the include path by default.  @xref{Miscellaneous
 137 configuring}.
 138
 139 @item -I @var{dir}
 140 @itemx --include=@var{dir}
 141
 142 Appends directory @var{dir} to the path that is searched for include
 143 files in PSPP syntax files.
 144
 145 @item --testing-mode
 146
 147 Invoke heuristics to assist with testing PSPP.  For use by @code{make
 148 check} and similar scripts.
 149 @end table
 150
 151 @node Language control options
 152 @subsection Language control options
 153
 154 Language control options control how PSPP syntax files are parsed and
 155 interpreted.  The available language control options are:
 156
 157 @table @code
 158 @item -i
 159 @itemx --interactive
 160
 161 When a syntax file is specified on the command line, PSPP normally
 162 terminates after processing it.  Giving this option will cause PSPP to
 163 bring up a command prompt after processing the syntax file.
 164
 165 In addition, this forces syntax files to be interpreted in interactive
 166 mode, rather than the default batch mode.  @xref{Tokenizing lines}, for
 167 information on the differences between batch mode and interactive mode
 168 command interpretation.
 169
 170 @item -r
 171 @itemx --no-statrc
 172
 173 Prevents the execution of the PSPP startup syntax file.
 174
 175 @item -s
 176 @itemx --safer
 177
 178 Disables certain unsafe operations.  This includes the ERASE and
 179 HOST commands, as well as use of pipes as input and output files.
 180 @end table
 181
 182 @node Informational options
 183 @subsection Informational options
 184
 185 Informational options cause information about PSPP to be written to
 186 the terminal.  Here are the available options:
 187
 188 @table @code
 189 @item -h
 190 @item --help
 191
 192 Prints a message describing PSPP command-line syntax and the available
 193 device driver classes, then terminates.
 194
 195 @item -l
 196 @item --list
 197
 198 Lists the available device driver classes, then terminates.
 199
 200 @item -x @{compatible|enhanced@}
 201 @itemx --syntax=@{compatible|enhanced@}
 202
 203 If you chose @code{compatible}, then PSPP will only accept command syntax that
 204 is compatible with the proprietary program SPSS.
 205 If you choose @code{enhanced} then additional syntax will be available.
 206 The default is @code{enhanced}.
 207
 208
 209 @item -V
 210 @item --version
 211
 212 Prints a brief message listing PSPP's version, warranties you don't
 213 have, copying conditions and copyright, and e-mail address for bug
 214 reports, then terminates.
 215
 216 @item -v
 217 @item --verbose
 218
 219 Increments PSPP's verbosity level.  Higher verbosity levels cause
 220 PSPP to display greater amounts of information about what it is
 221 doing.  Often useful for debugging PSPP's configuration.
 222
 223 This option can be given multiple times to set the verbosity level to
 224 that value.  The default verbosity level is 0, in which no informational
 225 messages will be displayed.
 226
 227 Higher verbosity levels cause messages to be displayed when the
 228 corresponding events take place.
 229
 230 @table @asis
 231 @item 1
 232
 233 Driver and subsystem initializations.
 234
 235 @item 2
 236
 237 Completion of driver initializations.  Beginning of driver closings.
 238
 239 @item 3
 240
 241 Completion of driver closings.
 242
 243 @item 4
 244
 245 Files searched for; success of searches.
 246
 247 @item 5
 248
 249 Individual directories included in file searches.
 250 @end table
 251
 252 Each verbosity level also includes messages from lower verbosity levels.
 253
 254 @end table
 255
 256
 257 @node The graphic user interface
 258 @section The graphic user interface
 259
 260 @cindex Graphic user interface
 261 @cindex PSPPIRE
 262
 263 The graphic user interface can be started by typing @command{psppire} at a
 264 command prompt.
 265 Alternatively many systems have a system of interactive menus or buttons
 266 from which @command{psppire} can be started by a series of mouse clicks.
 267
 268 Once the principles of the PSPP system are understood,
 269 the graphic user interface is designed to be largely intuitive, and
 270 for this reason is covered only very briefly by this manual.