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