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 --table-look=@var{file}
56 -e, --error-file=@var{error-file}
59 @item Language options
61 -I, --include=@var{dir}
66 -a, --algorithm=@{compatible|enhanced@}
67 -x, --syntax=@{compatible|enhanced@}
68 --syntax-encoding=@var{encoding}
71 @item Informational options
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
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.
98 Use @samp{-} as @var{output-file} to write output to standard output.
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.
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.
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.
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.
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
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}
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.
143 Using @code{SET TLOOK} in @pspp{} syntax overrides the style set on
144 the command line (@pxref{SET}).
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.
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.
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}).
170 @item @option{--batch}
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.
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.
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.
190 Some commands have subcommands that override this setting on a per
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.
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}.
206 @item @option{--help}
207 Prints a message describing @pspp{} command-line syntax and the available
208 device formats, then exits.
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
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.
221 @item @option{--testing-mode}
222 Invoke heuristics to assist with testing @pspp{}. For use
223 by @command{make check} and similar scripts.
226 @node PDF PostScript SVG and PNG Output Options
227 @section PDF, PostScript, SVG, and PNG Output Options
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. These output formats are only available if your
237 installation of @pspp{} was compiled with the Cairo library.
239 PDF, PostScript, and SVG use real units: each dimension among the
240 options listed below may have a suffix @samp{mm} for millimeters,
241 @samp{in} for inches, or @samp{pt} for points. Lacking a suffix,
242 numbers below 50 are assumed to be in inches and those about 50 are
243 assumed to be in millimeters.
245 PNG files are pixel-based, so dimensions in PNG output must ultimately
246 be measured in pixels. For output to these files, PSPP translates the
247 specified dimensions to pixels at 72 pixels per inch. For PNG output
248 only, fonts are by default rendered larger than this, at 96 pixels per
251 An SVG or PNG file can only hold a single page. When PSPP outputs
252 more than one page to SVG or PNG, it creates multiple files. It
253 outputs the second page to a file named with a @code{-2} suffix, the
254 third with a @code{-3} suffix, and so on.
257 @item @option{-O format=@{pdf|ps|svg|png@}}
258 Specify the output format. This is only necessary if the file name
259 given on @option{-o} does not end in @file{.pdf}, @file{.ps},
260 @file{.svg}, or @file{.png}.
262 @item @option{-O paper-size=@var{paper-size}}
263 Paper size, as a name (@i{e.g.}@: @code{a4}, @code{letter}) or
264 measurements (@i{e.g.}@: @code{210x297}, @code{8.5x11in}).
266 The default paper size is taken from the @env{PAPERSIZE} environment
267 variable or the file indicated by the @env{PAPERCONF} environment
268 variable, if either variable is set. If not, and your system supports
269 the @code{LC_PAPER} locale category, then the default paper size is
270 taken from the locale. Otherwise, if @file{/etc/papersize} exists,
271 the default paper size is read from it. As a last resort, A4 paper is
274 @item @option{-O foreground-color=@var{color}}
275 Sets @var{color} as the default color for lines and text. Use a CSS
276 color format (e.g.@: @code{#@var{rr}@var{gg}@var{bb}}) or name (e.g.@:
277 @code{black}) as @var{color}.
279 @item @option{-O orientation=@var{orientation}}
280 Either @code{portrait} or @code{landscape}. Default: @code{portrait}.
282 @item @option{-O left-margin=@var{dimension}}
283 @itemx @option{-O right-margin=@var{dimension}}
284 @itemx @option{-O top-margin=@var{dimension}}
285 @itemx @option{-O bottom-margin=@var{dimension}}
286 Sets the margins around the page. See
287 below for the allowed forms of @var{dimension} Default: @code{0.5in}.
289 @item @option{-O prop-font=@var{font-name}}
290 @itemx @option{-O fixed-font=@var{font-name}}
291 Sets the font used for proportional, or fixed-pitch text. Most
292 systems support CSS-like font names such as ``serif'' and
293 ``monospace'', but a wide range of system-specific font are likely to
294 be supported as well.
296 Default: proportional font @code{serif}, fixed-pitch font @code{monospace}.
298 @item @option{-O font-size=@var{font-size}}
299 Sets the size of the default fonts, in thousandths of a point. Default:
302 @item @option{-O trim=true}
303 This option makes PSPP trim empty space around each page of output,
304 before adding the margins. This can make the output easier to include
307 @item @option{-O font-resolution=@var{dpi}}
308 Sets the resolution for font rendering, in dots per inch. For PDF,
309 PostScript, and SVG output, the default is 72 dpi, so that a 10-point
310 font is rendered with a height of 10 points. For PNG output, the
311 default is 96 dpi, so that a 10-point font is rendered with a height
312 of @math{10 / 72 * 96 = 13.3} pixels. Use a larger @var{dpi} to
313 enlarge text output, or a smaller @var{dpi} to shrink it.
316 @node Plain Text Output Options
317 @section Plain Text Output Options
319 @pspp{} can produce plain text output, drawing boxes using ASCII or
320 Unicode line drawing characters. To produce plain text output,
321 specify @option{-o @var{file}} on the @pspp{} command line, optionally
322 followed by options from the table below to customize the output
325 Plain text output is encoded in UTF-8.
328 @item @option{-O format=txt}
329 Specify the output format. This is only necessary if the file name
330 given on @option{-o} does not end in @file{.txt} or @file{.list}.
332 @item @option{-O charts=@{@var{template}.png|none@}}
333 Name for chart files included in output. The value should be a file
334 name that includes a single @samp{#} and ends in @file{png}. When a
335 chart is output, the @samp{#} is replaced by the chart number. The
336 default is the file name specified on @option{-o} with the extension
337 stripped off and replaced by @file{-#.png}.
339 Specify @code{none} to disable chart output. Charts are always
340 disabled if your installation of @pspp{} was compiled without the
343 @item @option{-O foreground-color=@var{color}}
344 @itemx @option{-O background-color=@var{color}}
345 Sets @var{color} as the color to be used for the background or foreground to
347 Color should be given in the format @code{#@var{RRRR}@var{GGGG}@var{BBBB}},
348 where @var{RRRR}, @var{GGGG} and @var{BBBB} are 4 character hexadecimal
349 representations of the red, green and blue components respectively.
350 If charts are disabled, this option has no effect.
352 @item @option{-O width=@var{columns}}
353 Width of a page, in columns. If unspecified or given as @code{auto},
354 the default is the width of the terminal, for interactive output, or
355 the WIDTH setting (@pxref{SET}), for output to a file.
357 @item @option{-O box=@{ascii|unicode@}}
358 Sets the characters used for lines in tables.
360 @code{ascii} the characters @samp{-}, @samp{|}, and @samp{+} for single-width
361 lines and @samp{=} and @samp{#} for double-width lines are used.
362 If set to @code{unicode} then Unicode box drawing characters will be used.
363 The default is @code{unicode} if the locale's character encoding is "UTF-8"
364 or @code{ascii} otherwise.
366 @item @option{-O emphasis=@{none|bold|underline@}}
367 How to emphasize text. Bold and underline emphasis are achieved with
368 overstriking, which may not be supported by all the software to which
369 you might pass the output. Default: @code{none}.
372 @node TeX Output Options
373 @section TeX Output Options
377 If you want to publish statistical results in professional or academic
378 journals, you will probably want to provide results in @TeX{} format.
379 To do this, specify @option{-o @var{file}} on the @pspp{} command line where
380 @var{file} is a file name ending in @file{.tex}, or you can specify
381 @option{-O format=tex}.
383 The resulting file can be directly processed using @TeX{} or you can manually
384 edit the file to add commentary text.
385 Alternatively, you can cut and paste desired sections to another @TeX{} file.
387 @node HTML Output Options
388 @section HTML Output Options
390 To produce output in HTML format, specify @option{-o @var{file}} on
391 the @pspp{} command line, optionally followed by any of the options shown
392 in the table below to customize the output format.
395 @item @option{-O format=html}
396 Specify the output format. This is only necessary if the file name
397 given on @option{-o} does not end in @file{.html}.
399 @item @option{-O charts=@{@var{template}.png|none@}}
400 Sets the name used for chart files. @xref{Plain Text Output Options},
403 @item @option{-O borders=@var{boolean}}
404 Decorate the tables with borders. If set to false, the tables produced
405 will have no borders. The default value is true.
407 @item @option{-O bare=@var{boolean}}
408 The HTML output driver ordinarily outputs a complete HTML document.
409 If set to true, the driver instead outputs only what would normally be
410 the contents of the @code{body} element. The default value is false.
412 @item @option{-O css=@var{boolean}}
413 Use cascading style sheets. Cascading style sheets give an improved appearance
414 and can be used to produce pages which fit a certain web site's style.
415 The default value is true.
419 @node OpenDocument Output Options
420 @section OpenDocument Output Options
422 To produce output as an OpenDocument text (ODT) document, specify
423 @option{-o @var{file}} on the @pspp{} command line. If @var{file} does
424 not end in @file{.odt}, you must also specify @option{-O format=odt}.
426 ODT support is only available if your installation of @pspp{} was
427 compiled with the libxml2 library.
429 The OpenDocument output format does not have any configurable options.
431 @node Comma-Separated Value Output Options
432 @section Comma-Separated Value Output Options
434 To produce output in comma-separated value (CSV) format, specify
435 @option{-o @var{file}} on the @pspp{} command line, optionally followed
436 by any of the options shown in the table below to customize the output
440 @item @option{-O format=csv}
441 Specify the output format. This is only necessary if the file name
442 given on @option{-o} does not end in @file{.csv}.
444 @item @option{-O separator=@var{field-separator}}
445 Sets the character used to separate fields. Default: a comma
448 @item @option{-O quote=@var{qualifier}}
449 Sets @var{qualifier} as the character used to quote fields that
450 contain white space, the separator (or any of the characters in the
451 separator, if it contains more than one character), or the quote
452 character itself. If @var{qualifier} is longer than one character,
453 only the first character is used; if @var{qualifier} is the empty
454 string, then fields are never quoted.
456 @item @option{-O titles=@var{boolean}}
457 Whether table titles (brief descriptions) should be printed. Default:
460 @item @option{-O captions=@var{boolean}}
461 Whether table captions (more extensive descriptions) should be
462 printed. Default: on.
465 The CSV format used is an extension to that specified in RFC 4180:
469 Each table row is output on a separate line, and each column is output
470 as a field. The contents of a cell that spans multiple rows or
471 columns is output only for the top-left row and column; the rest are
472 output as empty fields.
475 When a table has a title and titles are enabled, the title is output
476 just above the table as a single field prefixed by @samp{Table:}.
479 When a table has a caption and captions are enabled, the caption is
480 output just below the table as a single field prefixed by
484 Within a table, footnote markers are output as bracketed letters
485 following the cell's contents, @i{e.g.}@tie{}@samp{[a]}, @samp{[b]},
486 @enddots{} The footnotes themselves are output following the body of
487 the table, as a separate two-column table introduced with a line that
488 says @samp{Footnotes:}. Each row in the table represent one footnote:
489 the first column is the marker, the second column is the text.
492 Text in output is printed as a field on a line by itself. The TITLE
493 and SUBTITLE produce similar output, prefixed by @samp{Title:} or
494 @samp{Subtitle:}, respectively.
497 Errors, warnings, and notes are printed the same way as text.
500 Charts are not included in CSV output.
503 Successive output items are separated by a blank line.
505 @node Invoking PSPPIRE
506 @chapter Invoking @command{psppire}
507 @section The graphic user interface
508 @cindex Graphic user interface
511 The PSPPIRE graphic user interface for @pspp{} can perform all
512 functionality of the command line interface. In addition it gives an
513 instantaneous view of the data, variables and statistical output.
515 The graphic user interface can be started by typing @command{psppire} at a
517 Alternatively many systems have a system of interactive menus or buttons
518 from which @command{psppire} can be started by a series of mouse clicks.
520 Once the principles of the @pspp{} system are understood,
521 the graphic user interface is designed to be largely intuitive, and
522 for this reason is covered only very briefly by this manual.