tests: Avoid reading $HOME/.pspprc inside the testsuite.
[pspp-builds.git] / 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.  The default is a comma
383 (@samp{,}).
384 @end table
385
386 The CSV format used is an extension to that specified in RFC 4180:
387
388 @table @asis
389 @item Tables
390 Each table row is output on a separate line, and each column is output
391 as a field.  The contents of a cell that spans multiple rows or
392 columns is output only for the top-left row and column; the rest are
393 output as empty fields.  When a table has a caption, it is output just
394 above the table as a single field prefixed by @samp{Table:}.
395
396 @item Text
397 Text in output is printed as a field on a line by itself.  The TITLE
398 and SUBTITLE produce similar output, prefixed by @samp{Title:} or
399 @samp{Subtitle:}, respectively.
400
401 @item Messages
402 Errors, warnings, and notes are printed the same way as text.
403
404 @item Charts
405 Charts are not included in CSV output.
406 @end table
407
408 Successive output items are separated by a blank line.
409
410 @node Invoking PSPPIRE
411 @chapter Invoking @command{psppire}
412 @section The graphic user interface
413 @cindex Graphic user interface
414 @cindex PSPPIRE
415
416 The PSPPIRE graphic user interface for PSPP can perform all
417 functionality of the command line interface.  In addition it gives an
418 instantaneous view of the data, variables and statistical output.
419
420 The graphic user interface can be started by typing @command{psppire} at a 
421 command prompt.
422 Alternatively many systems have a system of interactive menus or buttons 
423 from which @command{psppire} can be started by a series of mouse clicks.
424
425 Once the principles of the PSPP system are understood, 
426 the graphic user interface is designed to be largely intuitive, and
427 for this reason is covered only very briefly by this manual.