Updated the developers' manual to reflect the new situation
[pspp-builds.git] / 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.