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
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.
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
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.
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}.
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}).
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
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}.
278 @item @option{-O orientation=@var{orientation}}
279 Either @code{portrait} or @code{landscape}. Default: @code{portrait}.
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}.
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.
293 Default: proportional font @code{Sans Serif}.
295 @item @option{-O font-size=@var{font-size}}
296 Sets the size of the default fonts, in thousandths of a point. Default:
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
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
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.
322 @node Plain Text Output Options
323 @section Plain Text Output Options
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
331 Plain text output is encoded in UTF-8.
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}.
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}.
345 Specify @code{none} to disable chart output.
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
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.
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.
361 @item @option{-O box=@{ascii|unicode@}}
362 Sets the characters used for lines in tables.
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.
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}.
376 @node TeX Output Options
377 @section TeX Output Options
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}.
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.
391 @node HTML Output Options
392 @section HTML Output Options
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.
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}.
403 @item @option{-O charts=@{@var{template}.png|none@}}
404 Sets the name used for chart files. @xref{Plain Text Output Options},
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.
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.
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.
423 @node OpenDocument Output Options
424 @section OpenDocument Output Options
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}.
430 ODT support is only available if your installation of @pspp{} was
431 compiled with the libxml2 library.
433 The OpenDocument output format does not have any configurable options.
435 @node Comma-Separated Value Output Options
436 @section Comma-Separated Value Output Options
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
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}.
448 @item @option{-O separator=@var{field-separator}}
449 Sets the character used to separate fields. Default: a comma
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.
460 @item @option{-O titles=@var{boolean}}
461 Whether table titles (brief descriptions) should be printed. Default:
464 @item @option{-O captions=@var{boolean}}
465 Whether table captions (more extensive descriptions) should be
466 printed. Default: on.
469 The CSV format used is an extension to that specified in RFC 4180:
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.
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:}.
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
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.
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.
501 Errors, warnings, and notes are printed the same way as text.
504 Charts are not included in CSV output.
507 Successive output items are separated by a blank line.
509 @node Invoking PSPPIRE
510 @chapter Invoking @command{psppire}
511 @section The graphic user interface
512 @cindex Graphic user interface
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.
519 The graphic user interface can be started by typing @command{psppire} at a
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.
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.