Fix warnings
[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 -b, --batch
53 -i, --interactive
54 -r, --no-statrc
55 -a, --algorithm=@{compatible|enhanced@}
56 -x, --syntax=@{compatible|enhanced@}
57 --syntax-encoding=@var{encoding}
58 @end example
59
60 @item Informational options
61 @example
62 -h, --help
63 -V, --version
64 @end example
65
66 @item Other options
67 @example
68 -s, --safer
69 --testing-mode
70 @end example
71 @end table
72
73 @table @code
74 @item @var{syntax-file}
75 Read and execute the named syntax file.  If no syntax files are
76 specified, PSPP prompts for commands.  If any syntax files are
77 specified, PSPP by default exits after it runs them, but you may make
78 it prompt for commands by specifying @samp{-} as an additional syntax
79 file.
80
81 @item -o @var{output-file}
82 Write output to @var{output-file}.  PSPP has several different output
83 drivers that support output in various formats (use @option{--help} to
84 list the available formats).  Specify this option more than once to
85 produce multiple output files, presumably in different formats.
86
87 Use @samp{-} as @var{output-file} to write output to standard output.
88
89 If no @option{-o} option is used, then PSPP writes output to standard
90 output in plain text format.
91
92 @item -O @var{option}=@var{value}
93 Sets an option for the output file configured by a preceding
94 @option{-o}.  Most options are specific to particular output formats.
95 A few options that apply generically are listed below.
96
97 @item -O format=@var{format}
98 PSPP uses the extension of the file name given on @option{-o} to
99 select an output format.  Use this option to override this choice by
100 specifying an alternate format, e.g.@: @option{-o pspp.out -O html} to
101 write HTML to a file named @file{pspp.out}.  Use @option{--help} to
102 list the available formats.
103
104 @item -O device=@{terminal|listing@}
105 Sets whether PSPP considers the output device configured by the
106 preceding @option{-o} to be a terminal or a listing device.  This
107 affects what output will be sent to the device, as configured by the
108 SET command's output routing subcommands (@pxref{SET}).  By default,
109 output written to standard output is considered a terminal device and
110 other output is considered a listing device.
111
112 @item --no-output
113 Disables output entirely, if neither @option{-o} nor @option{-O} is
114 also used.  If one of those options is used, @option{--no-output} has
115 no effect.
116
117 @item -e @var{error-file}
118 @itemx --error-file=@var{error-file}
119 Configures a file to receive PSPP error, warning, and note messages in
120 plain text format.  Use @samp{-} as @var{error-file} to write messages
121 to standard output.  The default error file is standard output in the
122 absence of these options, but this is suppressed if an output device
123 writes to standard output (or another terminal), to avoid printing
124 every message twice.  Use @samp{none} as @var{error-file} to
125 explicitly suppress the default.
126
127 @item -I @var{dir}
128 @itemx --include=@var{dir}
129 Appends @var{dir} to the set of directories searched by INCLUDE
130 (@pxref{INCLUDE}) and INSERT (@pxref{INSERT}).
131
132 @item -I-
133 @itemx --no-include
134 Clears all directories from the include path, including directories
135 inserted in the include path by default.  The default include path is
136 @file{.} (the current directory), followed by @file{.pspp} in the
137 user's home directory, followed by PSPP's system configuration
138 directory (usually @file{/etc/pspp} or @file{/usr/local/etc/pspp}).
139
140 @item -b
141 @item --batch
142 @item -i
143 @itemx --interactive
144 These options forces syntax files to be interpreted in batch mode or
145 interactive mode, respectively, rather than the default ``auto'' mode.
146 @xref{Syntax Variants}, for a description of the differences.
147
148 @item -r
149 @itemx --no-statrc
150 Disables running @file{rc} at PSPP startup time.
151
152 @item -a @{enhanced|compatible@}
153 @itemx --algorithm=@{enhanced|compatible@}
154 With @code{enhanced}, the default, PSPP uses the best implemented
155 algorithms for statistical procedures.  With @code{compatible},
156 however, PSPP will in some cases use inferior algorithms to produce
157 the same results as the proprietary program SPSS.
158
159 Some commands have subcommands that override this setting on a per
160 command basis.
161
162 @item -x @{enhanced|compatible@}
163 @itemx --syntax=@{enhanced|compatible@}
164 With @code{enhanced}, the default, PSPP accepts its own extensions
165 beyond those compatible with the proprietary program SPSS.  With
166 @code{compatible}, PSPP rejects syntax that uses these extensions.
167
168 @item --syntax-encoding=@var{encoding}
169 Specifies @var{encoding} as the encoding for syntax files named on the
170 command line.  The @var{encoding} also becomes the default encoding
171 for other syntax files read during the PSPP session by the
172 @cmd{INCLUDE} and @cmd{INSERT} commands.  @xref{INSERT}, for the
173 accepted forms of @var{encoding}.
174
175 @item --help
176 Prints a message describing PSPP command-line syntax and the available
177 device formats, then exits.
178
179 @item -V
180 @itemx --version
181 Prints a brief message listing PSPP's version, warranties you don't
182 have, copying conditions and copyright, and e-mail address for bug
183 reports, then exits.
184
185 @item -s
186 @itemx --safer
187 Disables certain unsafe operations.  This includes the ERASE and
188 HOST commands, as well as use of pipes as input and output files.
189
190 @item --testing-mode
191 Invoke heuristics to assist with testing PSPP.  For use by @code{make
192 check} and similar scripts.
193 @end table
194
195 @node PDF PostScript and SVG Output Options
196 @section PDF, PostScript, and SVG Output Options
197 @cindex PDF
198 @cindex Postscript
199 @cindex SVG
200
201 To produce output in PDF, PostScript, and SVG formats, specify
202 @option{-o @var{file}} on the PSPP command line, optionally followed
203 by any of the options shown in the table below to customize the output
204 format.
205
206 PDF, PostScript, and SVG output is only available if your installation
207 of PSPP was compiled with the Cairo library.
208
209 @table @code
210 @item -O format=@{pdf|ps|svg@}
211 Specify the output format.  This is only necessary if the file name
212 given on @option{-o} does not end in @file{.pdf}, @file{.ps}, or
213 @file{.svg}.
214
215 @item -O paper-size=@var{paper-size}
216 Paper size, as a name (e.g.@: @code{a4}, @code{letter}) or
217 measurements (e.g.@: @code{210x297}, @code{8.5x11in}).
218
219 The default paper size is taken from the @env{PAPERSIZE} environment
220 variable or the file indicated by the @env{PAPERCONF} environment
221 variable, if either variable is set.  If not, and your system supports
222 the @code{LC_PAPER} locale category, then the default paper size is
223 taken from the locale.  Otherwise, if @file{/etc/papersize} exists,
224 the default paper size is read from it.  As a last resort, A4 paper is
225 assumed.
226
227 @item -O foreground-color=@var{color}
228 @itemx -O background-color=@var{color}
229 Sets @var{color} as the color to be used for the background or foreground.
230 Color should be given in the format @code{#@var{RRRR}@var{GGGG}@var{BBBB}},
231 where @var{RRRR}, @var{GGGG} and @var{BBBB} are 4 character hexadecimal
232 representations of the red, green and blue components respectively.
233
234 @item -O orientation=@var{orientation}
235 Either @code{portrait} or @code{landscape}.  Default: @code{portrait}.
236
237 @item -O left-margin=@var{dimension}
238 @itemx -O right-margin=@var{dimension}
239 @itemx -O top-margin=@var{dimension}
240 @itemx -O bottom-margin=@var{dimension}
241 Sets the margins around the page.  See
242 below for the allowed forms of @var{dimension} Default: @code{0.5in}.
243
244 @item -O prop-font=@var{font-name}
245 @itemx -O emph-font=@var{font-name}
246 @itemx -O fixed-font=@var{font-name}
247 Sets the font used for proportional, emphasized, or fixed-pitch text.
248 Most systems support CSS-like font names such as ``serif'' and
249 ``monospace'', but a wide range of system-specific font are likely to
250 be supported as well.
251
252 Default: proportional font @code{serif}, emphasis font @code{serif
253 italic}, fixed-pitch font @code{monospace}.
254
255 @item -O font-size=@var{font-size}
256 Sets the size of the default fonts, in thousandths of a point.  Default:
257 10000 (10 point).
258
259 @item -O line-gutter=@var{dimension}
260 Sets the width of white space on either side of lines that border text
261 or graphics objects.  Default: @code{1pt}.
262
263 @item -O line-spacing=@var{dimension}
264 Sets the spacing between the lines in a double line in a table.
265 Default: @code{1pt}.
266
267 @item -O line-width=@var{dimension}
268 Sets the width of the lines used in tables.  Default: @code{0.5pt}.
269 @end table
270
271 Each @var{dimension} value above may be specified in various units
272 based on its suffix: @samp{mm} for millimeters, @samp{in} for inches,
273 or @samp{pt} for points.  Lacking a suffix, numbers below 50 are
274 assumed to be in inches and those about 50 are assumed to be in
275 millimeters.
276
277 @node Plain Text Output Options
278 @section Plain Text Output Options
279
280 PSPP can produce plain text output, drawing boxes using ASCII or
281 Unicode line drawing characters.  To produce plain text output,
282 specify @option{-o @var{file}} on the PSPP command line, optionally
283 followed by options from the table below to customize the output
284 format.
285
286 Plain text output is encoded in UTF-8.
287
288 @table @code
289 @item -O format=txt
290 Specify the output format.  This is only necessary if the file name
291 given on @option{-o} does not end in @file{.txt} or @file{.list}.
292
293 @item -O charts=@{@var{template}.png|none@}
294 Name for chart files included in output.  The value should be a file
295 name that includes a single @samp{#} and ends in @file{png}.  When a
296 chart is output, the @samp{#} is replaced by the chart number.  The
297 default is the file name specified on @option{-o} with the extension
298 stripped off and replaced by @file{-#.png}.
299
300 Specify @code{none} to disable chart output.  Charts are always
301 disabled if your installation of PSPP was compiled without the
302 Cairo library.
303
304 @item -O paginate=@var{boolean}
305 If set, PSPP writes an ASCII formfeed the end of every page.  Default:
306 @code{off}.
307
308 @item -O headers=@var{boolean}
309 If enabled, PSPP prints two lines of header information giving title
310 and subtitle, page number, date and time, and PSPP version are printed
311 at the top of every page.  These two lines are in addition to any top
312 margin requested.  Default: @code{off}.
313
314 @item -O length=@var{line-count}
315 Physical length of a page.  Headers and margins are subtracted from
316 this value.  You may specify the number of lines as a number, or for
317 screen output you may specify @code{auto} to track the height of the
318 terminal as it changes.  Default: @code{66}.
319
320 @item -O width=@var{character-count}
321 Width of a page, in characters.  Margins are subtracted from this
322 value.  For screen output you may specify @code{auto} in place of a
323 number to track the width of the terminal as it changes.  Default:
324 @code{79}.
325
326 @item -O top-margin=@var{top-margin-lines}
327 Length of the top margin, in lines.  PSPP subtracts this value from
328 the page length.  Default: @code{0}.
329
330 @item -O bottom-margin=@var{bottom-margin-lines}
331 Length of the bottom margin, in lines.  PSPP subtracts this value from
332 the page length.  Default: @code{0}.
333
334 @item -O box=@{ascii|unicode@}
335 Sets the characters used for lines in tables.  The default,
336 @code{ascii}, uses @samp{-}, @samp{|}, and @samp{+} for single-width
337 lines and @samp{=} and @samp{#} for double-width lines.  Specify
338 @code{unicode} to use Unicode box drawing characters.
339
340 @item -O emphasis=@{none|bold|underline@}
341 How to emphasize text.  Bold and underline emphasis are achieved with
342 overstriking, which may not be supported by all the software to which
343 you might pass the output.  Default: @code{none}.
344 @end table
345
346 @node HTML Output Options
347 @section HTML Output Options
348 @cindex HTML
349 To produce output in HTML format, specify @option{-o @var{file}} on
350 the PSPP command line, optionally followed by any of the options shown
351 in the table below to customize the output format.
352
353 @table @code
354 @item -O format=html
355 Specify the output format.  This is only necessary if the file name
356 given on @option{-o} does not end in @file{.html}.
357
358 @item -O charts=@{@var{template}.png|none@}
359 Sets the name used for chart files.  @xref{Plain Text Output Options},
360 for details.
361
362 @item -O borders=@var{boolean}
363 Decorate the tables with borders.  If set to false, the tables produced
364 will have no borders.  The default value is true.
365
366 @item -O css=@var{boolean}
367 Use cascading style sheets.  Cascading style sheets give an improved appearance
368 and can be used to produce pages which fit a certain web site's style.
369 The default value is true.
370
371 @end table
372
373 @node OpenDocument Output Options
374 @section OpenDocument Output Options
375
376 To produce output as an OpenDocument text (ODT) document, specify
377 @option{-o @var{file}} on the PSPP command line.  If @var{file} does
378 not end in @file{.odt}, you must also specify @option{-O format=odt}.
379
380 ODT support is only available if your installation of PSPP was
381 compiled with the libxml2 library.
382
383 The OpenDocument output format does not have any configurable options.
384
385 @node Comma-Separated Value Output Options
386 @section Comma-Separated Value Output Options
387
388 To produce output in comma-separated value (CSV) format, specify
389 @option{-o @var{file}} on the PSPP command line, optionally followed
390 by any of the options shown in the table below to customize the output
391 format.
392
393 @table @code
394 @item -O format=csv
395 Specify the output format.  This is only necessary if the file name
396 given on @option{-o} does not end in @file{.csv}.
397
398 @item -O separator=@var{field-separator}
399 Sets the character used to separate fields.  Default: a comma
400 (@samp{,}).
401
402 @item -O quote=@var{qualifier}
403 Sets @var{qualifier} as the character used to quote fields that
404 contain white space, the separator (or any of the characters in the
405 separator, if it contains more than one character), or the quote
406 character itself.  If @var{qualifier} is longer than one character,
407 only the first character is used; if @var{qualifier} is the empty
408 string, then fields are never quoted.
409
410 @item -O captions=@var{boolean}
411 Whether table captions should be printed.  Default: @code{on}.
412 @end table
413
414 The CSV format used is an extension to that specified in RFC 4180:
415
416 @table @asis
417 @item Tables
418 Each table row is output on a separate line, and each column is output
419 as a field.  The contents of a cell that spans multiple rows or
420 columns is output only for the top-left row and column; the rest are
421 output as empty fields.  When a table has a caption and captions are
422 enabled, the caption is output just above the table as a single field
423 prefixed by @samp{Table:}.
424
425 @item Text
426 Text in output is printed as a field on a line by itself.  The TITLE
427 and SUBTITLE produce similar output, prefixed by @samp{Title:} or
428 @samp{Subtitle:}, respectively.
429
430 @item Messages
431 Errors, warnings, and notes are printed the same way as text.
432
433 @item Charts
434 Charts are not included in CSV output.
435 @end table
436
437 Successive output items are separated by a blank line.
438
439 @node Invoking PSPPIRE
440 @chapter Invoking @command{psppire}
441 @section The graphic user interface
442 @cindex Graphic user interface
443 @cindex PSPPIRE
444
445 The PSPPIRE graphic user interface for PSPP can perform all
446 functionality of the command line interface.  In addition it gives an
447 instantaneous view of the data, variables and statistical output.
448
449 The graphic user interface can be started by typing @command{psppire} at a 
450 command prompt.
451 Alternatively many systems have a system of interactive menus or buttons 
452 from which @command{psppire} can be started by a series of mouse clicks.
453
454 Once the principles of the PSPP system are understood, 
455 the graphic user interface is designed to be largely intuitive, and
456 for this reason is covered only very briefly by this manual.