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 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::
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 SVG and PNG Output Options
209 @section PDF, PostScript, SVG, and PNG Output Options
215 To produce output in PDF, PostScript, SVG, or PNG format, specify
216 @option{-o @var{file}} on the @pspp{} command line, optionally
217 followed by any of the options shown in the table below to customize
218 the output format. These output formats are only available if your
219 installation of @pspp{} was compiled with the Cairo library.
221 PDF, PostScript, and SVG use real units: each dimension among the
222 options listed below may have a suffix @samp{mm} for millimeters,
223 @samp{in} for inches, or @samp{pt} for points. Lacking a suffix,
224 numbers below 50 are assumed to be in inches and those about 50 are
225 assumed to be in millimeters.
227 PNG files are pixel-based, so dimensions in PNG output must ultimately
228 be measured in pixels. For output to these files, PSPP translates the
229 specified dimensions to pixels at 72 pixels per inch. For PNG output
230 only, fonts are by default rendered larger than this, at 96 pixels per
233 An SVG or PNG file can only hold a single page. When PSPP outputs
234 more than one page to SVG or PNG, it creates multiple files. It
235 outputs the second page to a file named with a @code{-2} suffix, the
236 third with a @code{-3} suffix, and so on.
239 @item @option{-O format=@{pdf|ps|svg|png@}}
240 Specify the output format. This is only necessary if the file name
241 given on @option{-o} does not end in @file{.pdf}, @file{.ps},
242 @file{.svg}, or @file{.png}.
244 @item @option{-O paper-size=@var{paper-size}}
245 Paper size, as a name (@i{e.g.}@: @code{a4}, @code{letter}) or
246 measurements (@i{e.g.}@: @code{210x297}, @code{8.5x11in}).
248 The default paper size is taken from the @env{PAPERSIZE} environment
249 variable or the file indicated by the @env{PAPERCONF} environment
250 variable, if either variable is set. If not, and your system supports
251 the @code{LC_PAPER} locale category, then the default paper size is
252 taken from the locale. Otherwise, if @file{/etc/papersize} exists,
253 the default paper size is read from it. As a last resort, A4 paper is
256 @item @option{-O foreground-color=@var{color}}
257 Sets @var{color} as the default color for lines and text. Use a CSS
258 color format (e.g.@: @code{#@var{rr}@var{gg}@var{bb}}) or name (e.g.@:
259 @code{black}) as @var{color}.
261 @item @option{-O orientation=@var{orientation}}
262 Either @code{portrait} or @code{landscape}. Default: @code{portrait}.
264 @item @option{-O left-margin=@var{dimension}}
265 @itemx @option{-O right-margin=@var{dimension}}
266 @itemx @option{-O top-margin=@var{dimension}}
267 @itemx @option{-O bottom-margin=@var{dimension}}
268 Sets the margins around the page. See
269 below for the allowed forms of @var{dimension} Default: @code{0.5in}.
271 @item @option{-O prop-font=@var{font-name}}
272 @itemx @option{-O fixed-font=@var{font-name}}
273 Sets the font used for proportional, or fixed-pitch text. Most
274 systems support CSS-like font names such as ``serif'' and
275 ``monospace'', but a wide range of system-specific font are likely to
276 be supported as well.
278 Default: proportional font @code{serif}, fixed-pitch font @code{monospace}.
280 @item @option{-O font-size=@var{font-size}}
281 Sets the size of the default fonts, in thousandths of a point. Default:
284 @item @option{-O trim=true}
285 This option makes PSPP trim empty space around each page of output,
286 before adding the margins. This can make the output easier to include
289 @item @option{-O font-resolution=@var{dpi}}
290 Sets the resolution for font rendering, in dots per inch. For PDF,
291 PostScript, and SVG output, the default is 72 dpi, so that a 10-point
292 font is rendered with a height of 10 points. For PNG output, the
293 default is 96 dpi, so that a 10-point font is rendered with a height
294 of @math{10 / 72 * 96 = 13.3} pixels. Use a larger @var{dpi} to
295 enlarge text output, or a smaller @var{dpi} to shrink it.
298 @node Plain Text Output Options
299 @section Plain Text Output Options
301 @pspp{} can produce plain text output, drawing boxes using ASCII or
302 Unicode line drawing characters. To produce plain text output,
303 specify @option{-o @var{file}} on the @pspp{} command line, optionally
304 followed by options from the table below to customize the output
307 Plain text output is encoded in UTF-8.
310 @item @option{-O format=txt}
311 Specify the output format. This is only necessary if the file name
312 given on @option{-o} does not end in @file{.txt} or @file{.list}.
314 @item @option{-O charts=@{@var{template}.png|none@}}
315 Name for chart files included in output. The value should be a file
316 name that includes a single @samp{#} and ends in @file{png}. When a
317 chart is output, the @samp{#} is replaced by the chart number. The
318 default is the file name specified on @option{-o} with the extension
319 stripped off and replaced by @file{-#.png}.
321 Specify @code{none} to disable chart output. Charts are always
322 disabled if your installation of @pspp{} was compiled without the
325 @item @option{-O foreground-color=@var{color}}
326 @itemx @option{-O background-color=@var{color}}
327 Sets @var{color} as the color to be used for the background or foreground to
329 Color should be given in the format @code{#@var{RRRR}@var{GGGG}@var{BBBB}},
330 where @var{RRRR}, @var{GGGG} and @var{BBBB} are 4 character hexadecimal
331 representations of the red, green and blue components respectively.
332 If charts are disabled, this option has no effect.
334 @item @option{-O width=@var{columns}}
335 Width of a page, in columns. If unspecified or given as @code{auto},
336 the default is the width of the terminal, for interactive output, or
337 the WIDTH setting (@pxref{SET}), for output to a file.
339 @item @option{-O box=@{ascii|unicode@}}
340 Sets the characters used for lines in tables.
342 @code{ascii} the characters @samp{-}, @samp{|}, and @samp{+} for single-width
343 lines and @samp{=} and @samp{#} for double-width lines are used.
344 If set to @code{unicode} then Unicode box drawing characters will be used.
345 The default is @code{unicode} if the locale's character encoding is "UTF-8"
346 or @code{ascii} otherwise.
348 @item @option{-O emphasis=@{none|bold|underline@}}
349 How to emphasize text. Bold and underline emphasis are achieved with
350 overstriking, which may not be supported by all the software to which
351 you might pass the output. Default: @code{none}.
354 @node TeX Output Options
355 @section TeX Output Options
359 If you want to publish statistical results in professional or academic
360 journals, you will probably want to provide results in @TeX{} format.
361 To do this, specify @option{-o @var{file}} on the @pspp{} command line where
362 @var{file} is a file name ending in @file{.tex}, or you can specify
363 @option{-O format=tex}.
365 The resulting file can be directly processed using @TeX{} or you can manually
366 edit the file to add commentary text.
367 Alternatively, you can cut and paste desired sections to another @TeX{} file.
369 @node HTML Output Options
370 @section HTML Output Options
372 To produce output in HTML format, specify @option{-o @var{file}} on
373 the @pspp{} command line, optionally followed by any of the options shown
374 in the table below to customize the output format.
377 @item @option{-O format=html}
378 Specify the output format. This is only necessary if the file name
379 given on @option{-o} does not end in @file{.html}.
381 @item @option{-O charts=@{@var{template}.png|none@}}
382 Sets the name used for chart files. @xref{Plain Text Output Options},
385 @item @option{-O borders=@var{boolean}}
386 Decorate the tables with borders. If set to false, the tables produced
387 will have no borders. The default value is true.
389 @item @option{-O bare=@var{boolean}}
390 The HTML output driver ordinarily outputs a complete HTML document.
391 If set to true, the driver instead outputs only what would normally be
392 the contents of the @code{body} element. The default value is false.
394 @item @option{-O css=@var{boolean}}
395 Use cascading style sheets. Cascading style sheets give an improved appearance
396 and can be used to produce pages which fit a certain web site's style.
397 The default value is true.
401 @node OpenDocument Output Options
402 @section OpenDocument Output Options
404 To produce output as an OpenDocument text (ODT) document, specify
405 @option{-o @var{file}} on the @pspp{} command line. If @var{file} does
406 not end in @file{.odt}, you must also specify @option{-O format=odt}.
408 ODT support is only available if your installation of @pspp{} was
409 compiled with the libxml2 library.
411 The OpenDocument output format does not have any configurable options.
413 @node Comma-Separated Value Output Options
414 @section Comma-Separated Value Output Options
416 To produce output in comma-separated value (CSV) format, specify
417 @option{-o @var{file}} on the @pspp{} command line, optionally followed
418 by any of the options shown in the table below to customize the output
422 @item @option{-O format=csv}
423 Specify the output format. This is only necessary if the file name
424 given on @option{-o} does not end in @file{.csv}.
426 @item @option{-O separator=@var{field-separator}}
427 Sets the character used to separate fields. Default: a comma
430 @item @option{-O quote=@var{qualifier}}
431 Sets @var{qualifier} as the character used to quote fields that
432 contain white space, the separator (or any of the characters in the
433 separator, if it contains more than one character), or the quote
434 character itself. If @var{qualifier} is longer than one character,
435 only the first character is used; if @var{qualifier} is the empty
436 string, then fields are never quoted.
438 @item @option{-O titles=@var{boolean}}
439 Whether table titles (brief descriptions) should be printed. Default:
442 @item @option{-O captions=@var{boolean}}
443 Whether table captions (more extensive descriptions) should be
444 printed. Default: on.
447 The CSV format used is an extension to that specified in RFC 4180:
451 Each table row is output on a separate line, and each column is output
452 as a field. The contents of a cell that spans multiple rows or
453 columns is output only for the top-left row and column; the rest are
454 output as empty fields.
457 When a table has a title and titles are enabled, the title is output
458 just above the table as a single field prefixed by @samp{Table:}.
461 When a table has a caption and captions are enabled, the caption is
462 output just below the table as a single field prefixed by
466 Within a table, footnote markers are output as bracketed letters
467 following the cell's contents, @i{e.g.}@tie{}@samp{[a]}, @samp{[b]},
468 @enddots{} The footnotes themselves are output following the body of
469 the table, as a separate two-column table introduced with a line that
470 says @samp{Footnotes:}. Each row in the table represent one footnote:
471 the first column is the marker, the second column is the text.
474 Text in output is printed as a field on a line by itself. The TITLE
475 and SUBTITLE produce similar output, prefixed by @samp{Title:} or
476 @samp{Subtitle:}, respectively.
479 Errors, warnings, and notes are printed the same way as text.
482 Charts are not included in CSV output.
485 Successive output items are separated by a blank line.
487 @node Invoking PSPPIRE
488 @chapter Invoking @command{psppire}
489 @section The graphic user interface
490 @cindex Graphic user interface
493 The PSPPIRE graphic user interface for @pspp{} can perform all
494 functionality of the command line interface. In addition it gives an
495 instantaneous view of the data, variables and statistical output.
497 The graphic user interface can be started by typing @command{psppire} at a
499 Alternatively many systems have a system of interactive menus or buttons
500 from which @command{psppire} can be started by a series of mouse clicks.
502 Once the principles of the @pspp{} system are understood,
503 the graphic user interface is designed to be largely intuitive, and
504 for this reason is covered only very briefly by this manual.