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".
11 @chapter Invoking @command{pspp}
13 @cindex @pspp{}, invoking
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
20 The sections below describe the @command{pspp} program's command-line
25 * PDF PostScript and SVG 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::
36 Here is a summary of all the options, grouped by type, followed by
37 explanations in the same order.
39 In the table, arguments to long options also apply to any
40 corresponding short options.
43 @item Non-option arguments
50 -o, --output=@var{output-file}
51 -O @var{option}=@var{value}
52 -O format=@var{format}
53 -O device=@{terminal|listing@}
55 -e, --error-file=@var{error-file}
58 @item Language options
60 -I, --include=@var{dir}
65 -a, --algorithm=@{compatible|enhanced@}
66 -x, --syntax=@{compatible|enhanced@}
67 --syntax-encoding=@var{encoding}
70 @item Informational options
84 @item @var{syntax-file}
85 Read and execute the named syntax file. If no syntax files are
86 specified, @pspp{} prompts for commands. If any syntax files are
87 specified, @pspp{} by default exits after it runs them, but you may make
88 it prompt for commands by specifying @samp{-} as an additional syntax
91 @item @option{-o @var{output-file}}
92 Write output to @var{output-file}. @pspp{} has several different output
93 drivers that support output in various formats (use @option{--help} to
94 list the available formats). Specify this option more than once to
95 produce multiple output files, presumably in different formats.
97 Use @samp{-} as @var{output-file} to write output to standard output.
99 If no @option{-o} option is used, then @pspp{} writes text and CSV
100 output to standard output and other kinds of output to whose name is
101 based on the format, @i{e.g.}@: @file{pspp.pdf} for PDF output.
103 @item @option{-O @var{option}=@var{value}}
104 Sets an option for the output file configured by a preceding
105 @option{-o}. Most options are specific to particular output formats.
106 A few options that apply generically are listed below.
108 @item @option{-O format=@var{format}}
109 @pspp{} uses the extension of the file name given on @option{-o} to
110 select an output format. Use this option to override this choice by
111 specifying an alternate format, @i{e.g.}@: @option{-o pspp.out -O format=html} to
112 write HTML to a file named @file{pspp.out}. Use @option{--help} to
113 list the available formats.
115 @item @option{-O device=@{terminal|listing@}}
116 Sets whether @pspp{} considers the output device configured by the
117 preceding @option{-o} to be a terminal or a listing device. This
118 affects what output will be sent to the device, as configured by the
119 SET command's output routing subcommands (@pxref{SET}). By default,
120 output written to standard output is considered a terminal device and
121 other output is considered a listing device.
123 @item @option{--no-output}
124 Disables output entirely, if neither @option{-o} nor @option{-O} is
125 also used. If one of those options is used, @option{--no-output} has
128 @item @option{-e @var{error-file}}
129 @itemx @option{--error-file=@var{error-file}}
130 Configures a file to receive @pspp{} error, warning, and note messages in
131 plain text format. Use @samp{-} as @var{error-file} to write messages
132 to standard output. The default error file is standard output in the
133 absence of these options, but this is suppressed if an output device
134 writes to standard output (or another terminal), to avoid printing
135 every message twice. Use @samp{none} as @var{error-file} to
136 explicitly suppress the default.
138 @item @option{-I @var{dir}}
139 @itemx @option{--include=@var{dir}}
140 Appends @var{dir} to the set of directories searched by the @cmd{INCLUDE}
141 (@pxref{INCLUDE}) and @cmd{INSERT} (@pxref{INSERT}) commands.
144 @itemx @option{--no-include}
145 Clears all directories from the include path, including directories
146 inserted in the include path by default. The default include path is
147 @file{.} (the current directory), followed by @file{.pspp} in the
148 user's home directory, followed by @pspp{}'s system configuration
149 directory (usually @file{/etc/pspp} or @file{/usr/local/etc/pspp}).
152 @item @option{--batch}
154 @itemx @option{--interactive}
155 These options forces syntax files to be interpreted in batch mode or
156 interactive mode, respectively, rather than the default ``auto'' mode.
157 @xref{Syntax Variants}, for a description of the differences.
160 @itemx @option{--no-statrc}
161 By default, at startup @pspp{} searches for a file named @file{rc} in
162 the include path (described above) and, if it finds one, runs the
163 commands in it. This option disables this behavior.
165 @item @option{-a @{enhanced|compatible@}}
166 @itemx @option{--algorithm=@{enhanced|compatible@}}
167 With @code{enhanced}, the default, @pspp{} uses the best implemented
168 algorithms for statistical procedures. With @code{compatible},
169 however, @pspp{} will in some cases use inferior algorithms to produce
170 the same results as the proprietary program SPSS.
172 Some commands have subcommands that override this setting on a per
175 @item @option{-x @{enhanced|compatible@}}
176 @itemx @option{--syntax=@{enhanced|compatible@}}
177 With @code{enhanced}, the default, @pspp{} accepts its own extensions
178 beyond those compatible with the proprietary program SPSS. With
179 @code{compatible}, @pspp{} rejects syntax that uses these extensions.
181 @item @option{--syntax-encoding=@var{encoding}}
182 Specifies @var{encoding} as the encoding for syntax files named on the
183 command line. The @var{encoding} also becomes the default encoding
184 for other syntax files read during the @pspp{} session by the
185 @cmd{INCLUDE} and @cmd{INSERT} commands. @xref{INSERT}, for the
186 accepted forms of @var{encoding}.
188 @item @option{--help}
189 Prints a message describing @pspp{} command-line syntax and the available
190 device formats, then exits.
193 @itemx @option{--version}
194 Prints a brief message listing @pspp{}'s version, warranties you don't
195 have, copying conditions and copyright, and e-mail address for bug
199 @itemx @option{--safer}
200 Disables certain unsafe operations. This includes the @subcmd{ERASE} and
201 @subcmd{HOST} commands, as well as use of pipes as input and output files.
203 @item @option{--testing-mode}
204 Invoke heuristics to assist with testing @pspp{}. For use
205 by @command{make check} and similar scripts.
208 @node PDF PostScript and SVG Output Options
209 @section PDF, PostScript, and SVG Output Options
214 To produce output in PDF, PostScript, and SVG formats, specify
215 @option{-o @var{file}} on the @pspp{} command line, optionally followed
216 by any of the options shown in the table below to customize the output
219 PDF, PostScript, and SVG output is only available if your installation
220 of @pspp{} was compiled with the Cairo library.
223 @item @option{-O format=@{pdf|ps|svg@}}
224 Specify the output format. This is only necessary if the file name
225 given on @option{-o} does not end in @file{.pdf}, @file{.ps}, or
228 @item @option{-O paper-size=@var{paper-size}}
229 Paper size, as a name (@i{e.g.}@: @code{a4}, @code{letter}) or
230 measurements (@i{e.g.}@: @code{210x297}, @code{8.5x11in}).
232 The default paper size is taken from the @env{PAPERSIZE} environment
233 variable or the file indicated by the @env{PAPERCONF} environment
234 variable, if either variable is set. If not, and your system supports
235 the @code{LC_PAPER} locale category, then the default paper size is
236 taken from the locale. Otherwise, if @file{/etc/papersize} exists,
237 the default paper size is read from it. As a last resort, A4 paper is
240 @item @option{-O foreground-color=@var{color}}
241 @itemx @option{-O background-color=@var{color}}
242 Sets @var{color} as the color to be used for the background or foreground.
243 Color should be given in the format @code{#@var{RRRR}@var{GGGG}@var{BBBB}},
244 where @var{RRRR}, @var{GGGG} and @var{BBBB} are 4 character hexadecimal
245 representations of the red, green and blue components respectively.
247 @item @option{-O orientation=@var{orientation}}
248 Either @code{portrait} or @code{landscape}. Default: @code{portrait}.
250 @item @option{-O left-margin=@var{dimension}}
251 @itemx @option{-O right-margin=@var{dimension}}
252 @itemx @option{-O top-margin=@var{dimension}}
253 @itemx @option{-O bottom-margin=@var{dimension}}
254 Sets the margins around the page. See
255 below for the allowed forms of @var{dimension} Default: @code{0.5in}.
257 @item @option{-O prop-font=@var{font-name}}
258 @itemx @option{-O fixed-font=@var{font-name}}
259 Sets the font used for proportional, or fixed-pitch text. Most
260 systems support CSS-like font names such as ``serif'' and
261 ``monospace'', but a wide range of system-specific font are likely to
262 be supported as well.
264 Default: proportional font @code{serif}, fixed-pitch font @code{monospace}.
266 @item @option{-O font-size=@var{font-size}}
267 Sets the size of the default fonts, in thousandths of a point. Default:
270 @item @option{-O line-gutter=@var{dimension}}
271 Sets the width of white space on either side of lines that border text
272 or graphics objects. Default: @code{1pt}.
274 @item @option{-O line-spacing=@var{dimension}}
275 Sets the spacing between the lines in a double line in a table.
278 @item @option{-O line-width=@var{dimension}}
279 Sets the width of the lines used in tables. Default: @code{0.5pt}.
282 Each @var{dimension} value above may be specified in various units
283 based on its suffix: @samp{mm} for millimeters, @samp{in} for inches,
284 or @samp{pt} for points. Lacking a suffix, numbers below 50 are
285 assumed to be in inches and those about 50 are assumed to be in
288 @node Plain Text Output Options
289 @section Plain Text Output Options
291 @pspp{} can produce plain text output, drawing boxes using ASCII or
292 Unicode line drawing characters. To produce plain text output,
293 specify @option{-o @var{file}} on the @pspp{} command line, optionally
294 followed by options from the table below to customize the output
297 Plain text output is encoded in UTF-8.
300 @item @option{-O format=txt}
301 Specify the output format. This is only necessary if the file name
302 given on @option{-o} does not end in @file{.txt} or @file{.list}.
304 @item @option{-O charts=@{@var{template}.png|none@}}
305 Name for chart files included in output. The value should be a file
306 name that includes a single @samp{#} and ends in @file{png}. When a
307 chart is output, the @samp{#} is replaced by the chart number. The
308 default is the file name specified on @option{-o} with the extension
309 stripped off and replaced by @file{-#.png}.
311 Specify @code{none} to disable chart output. Charts are always
312 disabled if your installation of @pspp{} was compiled without the
315 @item @option{-O foreground-color=@var{color}}
316 @itemx @option{-O background-color=@var{color}}
317 Sets @var{color} as the color to be used for the background or foreground to
319 Color should be given in the format @code{#@var{RRRR}@var{GGGG}@var{BBBB}},
320 where @var{RRRR}, @var{GGGG} and @var{BBBB} are 4 character hexadecimal
321 representations of the red, green and blue components respectively.
322 If charts are disabled, this option has no effect.
324 @item @option{-O width=@var{columns}}
325 Width of a page, in columns. If unspecified or given as @code{auto},
326 the default is the width of the terminal, for interactive output, or
327 the WIDTH setting (@pxref{SET}), for output to a file.
329 @item @option{-O box=@{ascii|unicode@}}
330 Sets the characters used for lines in tables.
332 @code{ascii} the characters @samp{-}, @samp{|}, and @samp{+} for single-width
333 lines and @samp{=} and @samp{#} for double-width lines are used.
334 If set to @code{unicode} then Unicode box drawing characters will be used.
335 The default is @code{unicode} if the locale's character encoding is "UTF-8"
336 or @code{ascii} otherwise.
338 @item @option{-O emphasis=@{none|bold|underline@}}
339 How to emphasize text. Bold and underline emphasis are achieved with
340 overstriking, which may not be supported by all the software to which
341 you might pass the output. Default: @code{none}.
344 @node TeX Output Options
345 @section TeX Output Options
349 If you want to publish statistical results in professional or academic
350 journals, you will probably want to provide results in @TeX{} format.
351 To do this, specify @option{-o @var{file}} on the @pspp{} command line where
352 @var{file} is a file name ending in @file{.tex}, or you can specify
353 @option{-O format=tex}.
355 The resulting file can be directly processed using @TeX{} or you can manually
356 edit the file to add commentary text.
357 Alternatively, you can cut and paste desired sections to another @TeX{} file.
359 @node HTML Output Options
360 @section HTML Output Options
362 To produce output in HTML format, specify @option{-o @var{file}} on
363 the @pspp{} command line, optionally followed by any of the options shown
364 in the table below to customize the output format.
367 @item @option{-O format=html}
368 Specify the output format. This is only necessary if the file name
369 given on @option{-o} does not end in @file{.html}.
371 @item @option{-O charts=@{@var{template}.png|none@}}
372 Sets the name used for chart files. @xref{Plain Text Output Options},
375 @item @option{-O borders=@var{boolean}}
376 Decorate the tables with borders. If set to false, the tables produced
377 will have no borders. The default value is true.
379 @item @option{-O bare=@var{boolean}}
380 The HTML output driver ordinarily outputs a complete HTML document.
381 If set to true, the driver instead outputs only what would normally be
382 the contents of the @code{body} element. The default value is false.
384 @item @option{-O css=@var{boolean}}
385 Use cascading style sheets. Cascading style sheets give an improved appearance
386 and can be used to produce pages which fit a certain web site's style.
387 The default value is true.
391 @node OpenDocument Output Options
392 @section OpenDocument Output Options
394 To produce output as an OpenDocument text (ODT) document, specify
395 @option{-o @var{file}} on the @pspp{} command line. If @var{file} does
396 not end in @file{.odt}, you must also specify @option{-O format=odt}.
398 ODT support is only available if your installation of @pspp{} was
399 compiled with the libxml2 library.
401 The OpenDocument output format does not have any configurable options.
403 @node Comma-Separated Value Output Options
404 @section Comma-Separated Value Output Options
406 To produce output in comma-separated value (CSV) format, specify
407 @option{-o @var{file}} on the @pspp{} command line, optionally followed
408 by any of the options shown in the table below to customize the output
412 @item @option{-O format=csv}
413 Specify the output format. This is only necessary if the file name
414 given on @option{-o} does not end in @file{.csv}.
416 @item @option{-O separator=@var{field-separator}}
417 Sets the character used to separate fields. Default: a comma
420 @item @option{-O quote=@var{qualifier}}
421 Sets @var{qualifier} as the character used to quote fields that
422 contain white space, the separator (or any of the characters in the
423 separator, if it contains more than one character), or the quote
424 character itself. If @var{qualifier} is longer than one character,
425 only the first character is used; if @var{qualifier} is the empty
426 string, then fields are never quoted.
428 @item @option{-O titles=@var{boolean}}
429 Whether table titles (brief descriptions) should be printed. Default:
432 @item @option{-O captions=@var{boolean}}
433 Whether table captions (more extensive descriptions) should be
434 printed. Default: on.
437 The CSV format used is an extension to that specified in RFC 4180:
441 Each table row is output on a separate line, and each column is output
442 as a field. The contents of a cell that spans multiple rows or
443 columns is output only for the top-left row and column; the rest are
444 output as empty fields.
447 When a table has a title and titles are enabled, the title is output
448 just above the table as a single field prefixed by @samp{Table:}.
451 When a table has a caption and captions are enabled, the caption is
452 output just below the table as a single field prefixed by
456 Within a table, footnote markers are output as bracketed letters
457 following the cell's contents, @i{e.g.}@tie{}@samp{[a]}, @samp{[b]},
458 @enddots{} The footnotes themselves are output following the body of
459 the table, as a separate two-column table introduced with a line that
460 says @samp{Footnotes:}. Each row in the table represent one footnote:
461 the first column is the marker, the second column is the text.
464 Text in output is printed as a field on a line by itself. The TITLE
465 and SUBTITLE produce similar output, prefixed by @samp{Title:} or
466 @samp{Subtitle:}, respectively.
469 Errors, warnings, and notes are printed the same way as text.
472 Charts are not included in CSV output.
475 Successive output items are separated by a blank line.
477 @node Invoking PSPPIRE
478 @chapter Invoking @command{psppire}
479 @section The graphic user interface
480 @cindex Graphic user interface
483 The PSPPIRE graphic user interface for @pspp{} can perform all
484 functionality of the command line interface. In addition it gives an
485 instantaneous view of the data, variables and statistical output.
487 The graphic user interface can be started by typing @command{psppire} at a
489 Alternatively many systems have a system of interactive menus or buttons
490 from which @command{psppire} can be started by a series of mouse clicks.
492 Once the principles of the @pspp{} system are understood,
493 the graphic user interface is designed to be largely intuitive, and
494 for this reason is covered only very briefly by this manual.