Patch #6210: implement ability to resize output device parameters to
[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        [ -d @var{var}[=@var{value}] | --define=@var{var}[=@var{value}] ] [-u @var{var} | --undef=@var{var} ]
11        [ -f @var{file} | --out-file=@var{file} ] [ -p | --pipe ] [ -I- | --no-include ]
12        [ -I @var{dir} | --include=@var{dir} ] [ -i | --interactive ] 
13        [ -n | --edit | --dry-run | --just-print | --recon ] 
14        [ -r | --no-statrc ] [ -h | --help ] [ -l | --list ] 
15        [ -c @var{command} | --command @var{command} ] [ -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 may be 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 -f @var{file}
105 @itemx --out-file=@var{file}
106
107 This overrides the output file name for devices designated as listing
108 devices.  If a file named @var{file} already exists, it is overwritten.
109
110 @item -p
111 @itemx --pipe
112
113 Allows PSPP to be used as a filter by causing the syntax file to be
114 read from stdin and output to be written to stdout.  Conflicts with the
115 @code{-f @var{file}} and @code{--file=@var{file}} options.
116
117 @item -I-
118 @itemx --no-include
119
120 Clears all directories from the include path.  This includes all
121 directories put in the include path by default.  @xref{Miscellaneous
122 configuring}.
123
124 @item -I @var{dir}
125 @itemx --include=@var{dir}
126
127 Appends directory @var{dir} to the path that is searched for include
128 files in PSPP syntax files.
129
130 @item -c @var{command}
131 @itemx --command=@var{command}
132
133 Execute literal command @var{command}.  The command is executed before
134 startup syntax files, if any.
135
136 @item --testing-mode
137
138 Invoke heuristics to assist with testing PSPP.  For use by @code{make
139 check} and similar scripts.
140 @end table
141
142 @node Language control options
143 @section Language control options
144
145 Language control options control how PSPP syntax files are parsed and
146 interpreted.  The available language control options are:
147
148 @table @code
149 @item -i
150 @itemx --interactive
151
152 When a syntax file is specified on the command line, PSPP normally
153 terminates after processing it.  Giving this option will cause PSPP to
154 bring up a command prompt after processing the syntax file.
155
156 In addition, this forces syntax files to be interpreted in interactive
157 mode, rather than the default batch mode.  @xref{Tokenizing lines}, for
158 information on the differences between batch mode and interactive mode
159 command interpretation.
160
161 @item -n
162 @itemx --edit
163 @itemx --dry-run
164 @itemx --just-print
165 @itemx --recon
166
167 Only the syntax of any syntax file specified or of commands entered at
168 the command line is checked.  Transformations are not performed and
169 procedures are not executed.  Not yet implemented.
170
171 @item -r
172 @itemx --no-statrc
173
174 Prevents the execution of the PSPP startup syntax file.
175
176 @item -s
177 @itemx --safer
178
179 Disables certain unsafe operations.  This includes the ERASE and
180 HOST commands, as well as use of pipes as input and output files.
181 @end table
182
183 @node Informational options
184 @section Informational options
185
186 Informational options cause information about PSPP to be written to
187 the terminal.  Here are the available options:
188
189 @table @code
190 @item -h
191 @item --help
192
193 Prints a message describing PSPP command-line syntax and the available
194 device driver classes, then terminates.
195
196 @item -l
197 @item --list
198
199 Lists the available device driver classes, then terminates.
200
201 @item -x @{compatible|enhanced@}
202 @itemx --syntax=@{compatible|enhanced@}
203
204 If you chose @code{compatible}, then PSPP will only accept command syntax that 
205 is compatible with the proprietary program SPSS.
206 If you choose @code{enhanced} then additional syntax will be available.
207 The default is @code{enhanced}.
208
209
210 @item -V
211 @item --version
212
213 Prints a brief message listing PSPP's version, warranties you don't
214 have, copying conditions and copyright, and e-mail address for bug
215 reports, then terminates.
216
217 @item -v
218 @item --verbose
219
220 Increments PSPP's verbosity level.  Higher verbosity levels cause
221 PSPP to display greater amounts of information about what it is
222 doing.  Often useful for debugging PSPP's configuration.  
223
224 This option can be given multiple times to set the verbosity level to
225 that value.  The default verbosity level is 0, in which no informational
226 messages will be displayed.
227
228 Higher verbosity levels cause messages to be displayed when the
229 corresponding events take place.
230
231 @table @asis
232 @item 1
233
234 Driver and subsystem initializations.
235
236 @item 2
237
238 Completion of driver initializations.  Beginning of driver closings.
239
240 @item 3
241
242 Completion of driver closings.
243
244 @item 4
245
246 Files searched for; success of searches.
247
248 @item 5
249
250 Individual directories included in file searches.
251 @end table
252
253 Each verbosity level also includes messages from lower verbosity levels.
254
255 @end table
256 @setfilename ignored