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