better tests
[pspp] / doc / invoking.texi
1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2017, 2020 Free Software Foundation, Inc.
3 @c Permission is granted to copy, distribute and/or modify this document
4 @c under the terms of the GNU Free Documentation License, Version 1.3
5 @c or any later version published by the Free Software Foundation;
6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
7 @c A copy of the license is included in the section entitled "GNU
8 @c Free Documentation License".
9 @c
10 @node Invoking PSPP
11 @chapter Invoking @command{pspp}
12 @cindex invocation
13 @cindex @pspp{}, invoking
14
15 @pspp{} has two separate user interfaces.  This chapter describes
16 @command{pspp}, @pspp{}'s command-line driven text-based user interface.
17 The following chapter briefly describes PSPPIRE, the graphical user
18 interface to @pspp{}.
19
20 The sections below describe the @command{pspp} program's command-line
21 interface.
22
23 @menu
24 * Main Options::
25 * PDF PostScript SVG and PNG Output Options::
26 * Plain Text Output Options::
27 * TeX Output Options::
28 * HTML Output Options::
29 * OpenDocument Output Options::
30 * Comma-Separated Value Output Options::
31 @end menu
32
33 @node Main Options
34 @section Main Options
35
36 Here is a summary of all the options, grouped by type, followed by
37 explanations in the same order.
38
39 In the table, arguments to long options also apply to any
40 corresponding short options.
41
42 @table @emph
43 @item Non-option arguments
44 @example
45 @var{syntax-file}
46 @end example
47
48 @item Output options
49 @example
50 -o, --output=@var{output-file}
51 -O @var{option}=@var{value}
52 -O format=@var{format}
53 -O device=@{terminal|listing@}
54 --no-output
55 --table-look=@var{file}
56 -e, --error-file=@var{error-file}
57 @end example
58
59 @item Language options
60 @example
61 -I, --include=@var{dir}
62 -I-, --no-include
63 -b, --batch
64 -i, --interactive
65 -r, --no-statrc
66 -a, --algorithm=@{compatible|enhanced@}
67 -x, --syntax=@{compatible|enhanced@}
68 --syntax-encoding=@var{encoding}
69 @end example
70
71 @item Informational options
72 @example
73 -h, --help
74 -V, --version
75 @end example
76
77 @item Other options
78 @example
79 -s, --safer
80 --testing-mode
81 @end example
82 @end table
83
84 @table @asis
85 @item @var{syntax-file}
86 Read and execute the named syntax file.  If no syntax files are
87 specified, @pspp{} prompts for commands.  If any syntax files are
88 specified, @pspp{} by default exits after it runs them, but you may make
89 it prompt for commands by specifying @samp{-} as an additional syntax
90 file.
91
92 @item @option{-o @var{output-file}}
93 Write output to @var{output-file}.  @pspp{} has several different output
94 drivers that support output in various formats (use @option{--help} to
95 list the available formats).  Specify this option more than once to
96 produce multiple output files, presumably in different formats.
97
98 Use @samp{-} as @var{output-file} to write output to standard output.
99
100 If no @option{-o} option is used, then @pspp{} writes text and CSV
101 output to standard output and other kinds of output to whose name is
102 based on the format, @i{e.g.}@: @file{pspp.pdf} for PDF output.
103
104 @item @option{-O @var{option}=@var{value}}
105 Sets an option for the output file configured by a preceding
106 @option{-o}.  Most options are specific to particular output formats.
107 A few options that apply generically are listed below.
108
109 @item @option{-O format=@var{format}}
110 @pspp{} uses the extension of the file name given on @option{-o} to
111 select an output format.  Use this option to override this choice by
112 specifying an alternate format, @i{e.g.}@: @option{-o pspp.out -O format=html} to
113 write HTML to a file named @file{pspp.out}.  Use @option{--help} to
114 list the available formats.
115
116 @item @option{-O device=@{terminal|listing@}}
117 Sets whether @pspp{} considers the output device configured by the
118 preceding @option{-o} to be a terminal or a listing device.  This
119 affects what output will be sent to the device, as configured by the
120 SET command's output routing subcommands (@pxref{SET}).  By default,
121 output written to standard output is considered a terminal device and
122 other output is considered a listing device.
123
124 @item @option{--no-output}
125 Disables output entirely, if neither @option{-o} nor @option{-O} is
126 also used.  If one of those options is used, @option{--no-output} has
127 no effect.
128
129 @item @option{--table-look=@var{file}}
130 Reads a table style from @var{file} and applies it to all @pspp{}
131 table output.  The file should be a TableLook @file{.stt} or
132 @file{.tlo} file.  @pspp{} searches for @var{file} in the current
133 directory, then in @file{.pspp/looks} in the user's home directory,
134 then in a @file{looks} subdirectory inside @pspp{}'s data directory
135 (usually @file{/usr/local/share/pspp}).  If @pspp{} cannot find
136 @var{file} under the given name, it also tries adding a @file{.stt}
137 extension.
138
139 When this option is not specified, @pspp{} looks for
140 @file{default.stt} using the algorithm above, and otherwise it falls
141 back to a default built-in style.
142
143 Using @code{SET TLOOK} in @pspp{} syntax overrides the style set on
144 the command line (@pxref{SET}).
145
146 @item @option{-e @var{error-file}}
147 @itemx @option{--error-file=@var{error-file}}
148 Configures a file to receive @pspp{} error, warning, and note messages in
149 plain text format.  Use @samp{-} as @var{error-file} to write messages
150 to standard output.  The default error file is standard output in the
151 absence of these options, but this is suppressed if an output device
152 writes to standard output (or another terminal), to avoid printing
153 every message twice.  Use @samp{none} as @var{error-file} to
154 explicitly suppress the default.
155
156 @item @option{-I @var{dir}}
157 @itemx @option{--include=@var{dir}}
158 Appends @var{dir} to the set of directories searched by the @cmd{INCLUDE}
159 (@pxref{INCLUDE}) and @cmd{INSERT} (@pxref{INSERT}) commands.
160
161 @item @option{-I-}
162 @itemx @option{--no-include}
163 Clears all directories from the include path, including directories
164 inserted in the include path by default.  The default include path is
165 @file{.} (the current directory), followed by @file{.pspp} in the
166 user's home directory, followed by @pspp{}'s system configuration
167 directory (usually @file{/etc/pspp} or @file{/usr/local/etc/pspp}).
168
169 @item @option{-b}
170 @item @option{--batch}
171 @item @option{-i}
172 @itemx @option{--interactive}
173 These options forces syntax files to be interpreted in batch mode or
174 interactive mode, respectively, rather than the default ``auto'' mode.
175 @xref{Syntax Variants}, for a description of the differences.
176
177 @item @option{-r}
178 @itemx @option{--no-statrc}
179 By default, at startup @pspp{} searches for a file named @file{rc} in
180 the include path (described above) and, if it finds one, runs the
181 commands in it.  This option disables this behavior.
182
183 @item @option{-a @{enhanced|compatible@}}
184 @itemx @option{--algorithm=@{enhanced|compatible@}}
185 With @code{enhanced}, the default, @pspp{} uses the best implemented
186 algorithms for statistical procedures.  With @code{compatible},
187 however, @pspp{} will in some cases use inferior algorithms to produce
188 the same results as the proprietary program SPSS.
189
190 Some commands have subcommands that override this setting on a per
191 command basis.
192
193 @item @option{-x @{enhanced|compatible@}}
194 @itemx @option{--syntax=@{enhanced|compatible@}}
195 With @code{enhanced}, the default, @pspp{} accepts its own extensions
196 beyond those compatible with the proprietary program SPSS.  With
197 @code{compatible}, @pspp{} rejects syntax that uses these extensions.
198
199 @item @option{--syntax-encoding=@var{encoding}}
200 Specifies @var{encoding} as the encoding for syntax files named on the
201 command line.  The @var{encoding} also becomes the default encoding
202 for other syntax files read during the @pspp{} session by the
203 @cmd{INCLUDE} and @cmd{INSERT} commands.  @xref{INSERT}, for the
204 accepted forms of @var{encoding}.
205
206 @item @option{--help}
207 Prints a message describing @pspp{} command-line syntax and the available
208 device formats, then exits.
209
210 @item @option{-V}
211 @itemx @option{--version}
212 Prints a brief message listing @pspp{}'s version, warranties you don't
213 have, copying conditions and copyright, and e-mail address for bug
214 reports, then exits.
215
216 @item @option{-s}
217 @itemx @option{--safer}
218 Disables certain unsafe operations.  This includes the @subcmd{ERASE} and
219 @subcmd{HOST} commands, as well as use of pipes as input and output files.
220
221 @item @option{--testing-mode}
222 Invoke heuristics to assist with testing @pspp{}.  For use
223 by @command{make check} and similar scripts.
224 @end table
225
226 @node PDF PostScript SVG and PNG Output Options
227 @section PDF, PostScript, SVG, and PNG Output Options
228 @cindex PDF
229 @cindex Postscript
230 @cindex SVG
231 @cindex PNG
232
233 To produce output in PDF, PostScript, SVG, or PNG format, specify
234 @option{-o @var{file}} on the @pspp{} command line, optionally
235 followed by any of the options shown in the table below to customize
236 the output format.
237
238 PDF, PostScript, and SVG use real units: each dimension among the
239 options listed below may have a suffix @samp{mm} for millimeters,
240 @samp{in} for inches, or @samp{pt} for points.  Lacking a suffix,
241 numbers below 50 are assumed to be in inches and those about 50 are
242 assumed to be in millimeters.
243
244 PNG files are pixel-based, so dimensions in PNG output must ultimately
245 be measured in pixels.  For output to these files, PSPP translates the
246 specified dimensions to pixels at 72 pixels per inch.  For PNG output
247 only, fonts are by default rendered larger than this, at 96 pixels per
248 inch.
249
250 An SVG or PNG file can only hold a single page.  When PSPP outputs
251 more than one page to SVG or PNG, it creates multiple files.  It
252 outputs the second page to a file named with a @code{-2} suffix, the
253 third with a @code{-3} suffix, and so on.
254
255 @table @asis
256 @item @option{-O format=@{pdf|ps|svg|png@}}
257 Specify the output format.  This is only necessary if the file name
258 given on @option{-o} does not end in @file{.pdf}, @file{.ps},
259 @file{.svg}, or @file{.png}.
260
261 @item @option{-O paper-size=@var{paper-size}}
262 Paper size, as a name (@i{e.g.}@: @code{a4}, @code{letter}) or
263 measurements (@i{e.g.}@: @code{210x297}, @code{8.5x11in}).
264
265 The default paper size is taken from the @env{PAPERSIZE} environment
266 variable or the file indicated by the @env{PAPERCONF} environment
267 variable, if either variable is set.  If not, and your system supports
268 the @code{LC_PAPER} locale category, then the default paper size is
269 taken from the locale.  Otherwise, if @file{/etc/papersize} exists,
270 the default paper size is read from it.  As a last resort, A4 paper is
271 assumed.
272
273 @item @option{-O foreground-color=@var{color}}
274 Sets @var{color} as the default color for lines and text.  Use a CSS
275 color format (e.g.@: @code{#@var{rr}@var{gg}@var{bb}}) or name (e.g.@:
276 @code{black}) as @var{color}.
277
278 @item @option{-O orientation=@var{orientation}}
279 Either @code{portrait} or @code{landscape}.  Default: @code{portrait}.
280
281 @item @option{-O left-margin=@var{dimension}}
282 @itemx @option{-O right-margin=@var{dimension}}
283 @itemx @option{-O top-margin=@var{dimension}}
284 @itemx @option{-O bottom-margin=@var{dimension}}
285 Sets the margins around the page.  See
286 below for the allowed forms of @var{dimension} Default: @code{0.5in}.
287
288 @item @option{-O prop-font=@var{font-name}}
289 Sets the default font used for ordinary text.  Most systems support
290 CSS-like font names such as ``Sans Serif'', but a wide range of
291 system-specific fonts are likely to be supported as well.
292
293 Default: proportional font @code{Sans Serif}.
294
295 @item @option{-O font-size=@var{font-size}}
296 Sets the size of the default fonts, in thousandths of a point.  Default:
297 10000 (10 point).
298
299 @item @option{-O trim=true}
300 This option makes PSPP trim empty space around each page of output,
301 before adding the margins.  This can make the output easier to include
302 in other documents.
303
304 @item @option{-O outline=@var{boolean}}
305 For PDF output only, this option controls whether PSPP includes an
306 outline in the output file.  PDF viewers usually display the outline
307 as a side bar that allows for easy navigation of the file.
308 The default is true unless @option{-O trim=true} is also specified.
309 (The Cairo graphics library that PSPP uses to produce PDF output has a
310 bug that can cause a crash when outlines and trimming are used
311 together.)
312
313 @item @option{-O font-resolution=@var{dpi}}
314 Sets the resolution for font rendering, in dots per inch.  For PDF,
315 PostScript, and SVG output, the default is 72 dpi, so that a 10-point
316 font is rendered with a height of 10 points.  For PNG output, the
317 default is 96 dpi, so that a 10-point font is rendered with a height
318 of @math{10 / 72 * 96 = 13.3} pixels.  Use a larger @var{dpi} to
319 enlarge text output, or a smaller @var{dpi} to shrink it.
320 @end table
321
322 @node Plain Text Output Options
323 @section Plain Text Output Options
324
325 @pspp{} can produce plain text output, drawing boxes using ASCII or
326 Unicode line drawing characters.  To produce plain text output,
327 specify @option{-o @var{file}} on the @pspp{} command line, optionally
328 followed by options from the table below to customize the output
329 format.
330
331 Plain text output is encoded in UTF-8.
332
333 @table @asis
334 @item @option{-O format=txt}
335 Specify the output format.  This is only necessary if the file name
336 given on @option{-o} does not end in @file{.txt} or @file{.list}.
337
338 @item @option{-O charts=@{@var{template}.png|none@}}
339 Name for chart files included in output.  The value should be a file
340 name that includes a single @samp{#} and ends in @file{png}.  When a
341 chart is output, the @samp{#} is replaced by the chart number.  The
342 default is the file name specified on @option{-o} with the extension
343 stripped off and replaced by @file{-#.png}.
344
345 Specify @code{none} to disable chart output.
346
347 @item @option{-O foreground-color=@var{color}}
348 @itemx @option{-O background-color=@var{color}}
349 Sets @var{color} as the color to be used for the background or foreground to
350 be used for charts.
351 Color should be given in the format @code{#@var{RRRR}@var{GGGG}@var{BBBB}},
352 where @var{RRRR}, @var{GGGG} and @var{BBBB} are 4 character hexadecimal
353 representations of the red, green and blue components respectively.
354 If charts are disabled, this option has no effect.
355
356 @item @option{-O width=@var{columns}}
357 Width of a page, in columns.  If unspecified or given as @code{auto},
358 the default is the width of the terminal, for interactive output, or
359 the WIDTH setting (@pxref{SET}), for output to a file.
360
361 @item @option{-O box=@{ascii|unicode@}}
362 Sets the characters used for lines in tables.
363 If set to
364 @code{ascii} the characters @samp{-}, @samp{|}, and @samp{+} for single-width
365 lines and @samp{=} and @samp{#} for double-width lines are used.
366 If set to @code{unicode} then  Unicode box drawing characters will be used.
367 The default is @code{unicode} if the locale's character encoding is "UTF-8"
368 or @code{ascii} otherwise.
369
370 @item @option{-O emphasis=@{none|bold|underline@}}
371 How to emphasize text.  Bold and underline emphasis are achieved with
372 overstriking, which may not be supported by all the software to which
373 you might pass the output.  Default: @code{none}.
374 @end table
375
376 @node TeX Output Options
377 @section TeX Output Options
378 @cindex @TeX{}
379 @cindex tex
380
381 If you want to publish statistical results in professional or academic
382 journals, you will probably want to provide results in @TeX{} format.
383 To do this, specify @option{-o @var{file}} on the @pspp{} command line where
384 @var{file} is a file name ending in @file{.tex}, or you can specify
385 @option{-O format=tex}.
386
387 The resulting file can be directly processed using @TeX{} or you can manually
388 edit the file to add commentary text.
389 Alternatively, you can cut and paste desired sections to another @TeX{} file.
390
391 @node HTML Output Options
392 @section HTML Output Options
393 @cindex HTML
394 To produce output in HTML format, specify @option{-o @var{file}} on
395 the @pspp{} command line, optionally followed by any of the options shown
396 in the table below to customize the output format.
397
398 @table @asis
399 @item @option{-O format=html}
400 Specify the output format.  This is only necessary if the file name
401 given on @option{-o} does not end in @file{.html}.
402
403 @item @option{-O charts=@{@var{template}.png|none@}}
404 Sets the name used for chart files.  @xref{Plain Text Output Options},
405 for details.
406
407 @item @option{-O borders=@var{boolean}}
408 Decorate the tables with borders.  If set to false, the tables produced
409 will have no borders.  The default value is true.
410
411 @item @option{-O bare=@var{boolean}}
412 The HTML output driver ordinarily outputs a complete HTML document.
413 If set to true, the driver instead outputs only what would normally be
414 the contents of the @code{body} element.  The default value is false.
415
416 @item @option{-O css=@var{boolean}}
417 Use cascading style sheets.  Cascading style sheets give an improved appearance
418 and can be used to produce pages which fit a certain web site's style.
419 The default value is true.
420
421 @end table
422
423 @node OpenDocument Output Options
424 @section OpenDocument Output Options
425
426 To produce output as an OpenDocument text (ODT) document, specify
427 @option{-o @var{file}} on the @pspp{} command line.  If @var{file} does
428 not end in @file{.odt}, you must also specify @option{-O format=odt}.
429
430 ODT support is only available if your installation of @pspp{} was
431 compiled with the libxml2 library.
432
433 The OpenDocument output format does not have any configurable options.
434
435 @node Comma-Separated Value Output Options
436 @section Comma-Separated Value Output Options
437
438 To produce output in comma-separated value (CSV) format, specify
439 @option{-o @var{file}} on the @pspp{} command line, optionally followed
440 by any of the options shown in the table below to customize the output
441 format.
442
443 @table @asis
444 @item @option{-O format=csv}
445 Specify the output format.  This is only necessary if the file name
446 given on @option{-o} does not end in @file{.csv}.
447
448 @item @option{-O separator=@var{field-separator}}
449 Sets the character used to separate fields.  Default: a comma
450 (@samp{,}).
451
452 @item @option{-O quote=@var{qualifier}}
453 Sets @var{qualifier} as the character used to quote fields that
454 contain white space, the separator (or any of the characters in the
455 separator, if it contains more than one character), or the quote
456 character itself.  If @var{qualifier} is longer than one character,
457 only the first character is used; if @var{qualifier} is the empty
458 string, then fields are never quoted.
459
460 @item @option{-O titles=@var{boolean}}
461 Whether table titles (brief descriptions) should be printed.  Default:
462 @code{on}.
463
464 @item @option{-O captions=@var{boolean}}
465 Whether table captions (more extensive descriptions) should be
466 printed.  Default: on.
467 @end table
468
469 The CSV format used is an extension to that specified in RFC 4180:
470
471 @table @asis
472 @item Tables
473 Each table row is output on a separate line, and each column is output
474 as a field.  The contents of a cell that spans multiple rows or
475 columns is output only for the top-left row and column; the rest are
476 output as empty fields.
477
478 @item Titles
479 When a table has a title and titles are enabled, the title is output
480 just above the table as a single field prefixed by @samp{Table:}.
481
482 @item Captions
483 When a table has a caption and captions are enabled, the caption is
484 output just below the table as a single field prefixed by
485 @samp{Caption:}.
486
487 @item Footnotes
488 Within a table, footnote markers are output as bracketed letters
489 following the cell's contents, @i{e.g.}@tie{}@samp{[a]}, @samp{[b]},
490 @enddots{}  The footnotes themselves are output following the body of
491 the table, as a separate two-column table introduced with a line that
492 says @samp{Footnotes:}.  Each row in the table represent one footnote:
493 the first column is the marker, the second column is the text.
494
495 @item Text
496 Text in output is printed as a field on a line by itself.  The TITLE
497 and SUBTITLE produce similar output, prefixed by @samp{Title:} or
498 @samp{Subtitle:}, respectively.
499
500 @item Messages
501 Errors, warnings, and notes are printed the same way as text.
502
503 @item Charts
504 Charts are not included in CSV output.
505 @end table
506
507 Successive output items are separated by a blank line.
508
509 @node Invoking PSPPIRE
510 @chapter Invoking @command{psppire}
511 @section The graphic user interface
512 @cindex Graphic user interface
513 @cindex PSPPIRE
514
515 The PSPPIRE graphic user interface for @pspp{} can perform all
516 functionality of the command line interface.  In addition it gives an
517 instantaneous view of the data, variables and statistical output.
518
519 The graphic user interface can be started by typing @command{psppire} at a
520 command prompt.
521 Alternatively many systems have a system of interactive menus or buttons
522 from which @command{psppire} can be started by a series of mouse clicks.
523
524 Once the principles of the @pspp{} system are understood,
525 the graphic user interface is designed to be largely intuitive, and
526 for this reason is covered only very briefly by this manual.