1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2017 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 * HTML Output Options::
28 * OpenDocument Output Options::
29 * Comma-Separated Value Output Options::
35 Here is a summary of all the options, grouped by type, followed by
36 explanations in the same order.
38 In the table, arguments to long options also apply to any
39 corresponding short options.
42 @item Non-option arguments
49 -o, --output=@var{output-file}
50 -O @var{option}=@var{value}
51 -O format=@var{format}
52 -O device=@{terminal|listing@}
54 -e, --error-file=@var{error-file}
57 @item Language options
59 -I, --include=@var{dir}
64 -a, --algorithm=@{compatible|enhanced@}
65 -x, --syntax=@{compatible|enhanced@}
66 --syntax-encoding=@var{encoding}
69 @item Informational options
83 @item @var{syntax-file}
84 Read and execute the named syntax file. If no syntax files are
85 specified, @pspp{} prompts for commands. If any syntax files are
86 specified, @pspp{} by default exits after it runs them, but you may make
87 it prompt for commands by specifying @samp{-} as an additional syntax
90 @item @option{-o @var{output-file}}
91 Write output to @var{output-file}. @pspp{} has several different output
92 drivers that support output in various formats (use @option{--help} to
93 list the available formats). Specify this option more than once to
94 produce multiple output files, presumably in different formats.
96 Use @samp{-} as @var{output-file} to write output to standard output.
98 If no @option{-o} option is used, then @pspp{} writes text and CSV
99 output to standard output and other kinds of output to whose name is
100 based on the format, e.g.@: @file{pspp.pdf} for PDF output.
102 @item @option{-O @var{option}=@var{value}}
103 Sets an option for the output file configured by a preceding
104 @option{-o}. Most options are specific to particular output formats.
105 A few options that apply generically are listed below.
107 @item @option{-O format=@var{format}}
108 @pspp{} uses the extension of the file name given on @option{-o} to
109 select an output format. Use this option to override this choice by
110 specifying an alternate format, e.g.@: @option{-o pspp.out -O html} to
111 write HTML to a file named @file{pspp.out}. Use @option{--help} to
112 list the available formats.
114 @item @option{-O device=@{terminal|listing@}}
115 Sets whether @pspp{} considers the output device configured by the
116 preceding @option{-o} to be a terminal or a listing device. This
117 affects what output will be sent to the device, as configured by the
118 SET command's output routing subcommands (@pxref{SET}). By default,
119 output written to standard output is considered a terminal device and
120 other output is considered a listing device.
122 @item @option{--no-output}
123 Disables output entirely, if neither @option{-o} nor @option{-O} is
124 also used. If one of those options is used, @option{--no-output} has
127 @item @option{-e @var{error-file}}
128 @itemx @option{--error-file=@var{error-file}}
129 Configures a file to receive @pspp{} error, warning, and note messages in
130 plain text format. Use @samp{-} as @var{error-file} to write messages
131 to standard output. The default error file is standard output in the
132 absence of these options, but this is suppressed if an output device
133 writes to standard output (or another terminal), to avoid printing
134 every message twice. Use @samp{none} as @var{error-file} to
135 explicitly suppress the default.
137 @item @option{-I @var{dir}}
138 @itemx @option{--include=@var{dir}}
139 Appends @var{dir} to the set of directories searched by the @cmd{INCLUDE}
140 (@pxref{INCLUDE}) and @cmd{INSERT} (@pxref{INSERT}) commands.
143 @itemx @option{--no-include}
144 Clears all directories from the include path, including directories
145 inserted in the include path by default. The default include path is
146 @file{.} (the current directory), followed by @file{.pspp} in the
147 user's home directory, followed by @pspp{}'s system configuration
148 directory (usually @file{/etc/pspp} or @file{/usr/local/etc/pspp}).
151 @item @option{--batch}
153 @itemx @option{--interactive}
154 These options forces syntax files to be interpreted in batch mode or
155 interactive mode, respectively, rather than the default ``auto'' mode.
156 @xref{Syntax Variants}, for a description of the differences.
159 @itemx @option{--no-statrc}
160 By default, at startup @pspp{} searches for a file named @file{rc} in
161 the include path (described above) and, if it finds one, runs the
162 commands in it. This option disables this behavior.
164 @item @option{-a @{enhanced|compatible@}}
165 @itemx @option{--algorithm=@{enhanced|compatible@}}
166 With @code{enhanced}, the default, @pspp{} uses the best implemented
167 algorithms for statistical procedures. With @code{compatible},
168 however, @pspp{} will in some cases use inferior algorithms to produce
169 the same results as the proprietary program SPSS.
171 Some commands have subcommands that override this setting on a per
174 @item @option{-x @{enhanced|compatible@}}
175 @itemx @option{--syntax=@{enhanced|compatible@}}
176 With @code{enhanced}, the default, @pspp{} accepts its own extensions
177 beyond those compatible with the proprietary program SPSS. With
178 @code{compatible}, @pspp{} rejects syntax that uses these extensions.
180 @item @option{--syntax-encoding=@var{encoding}}
181 Specifies @var{encoding} as the encoding for syntax files named on the
182 command line. The @var{encoding} also becomes the default encoding
183 for other syntax files read during the @pspp{} session by the
184 @cmd{INCLUDE} and @cmd{INSERT} commands. @xref{INSERT}, for the
185 accepted forms of @var{encoding}.
187 @item @option{--help}
188 Prints a message describing @pspp{} command-line syntax and the available
189 device formats, then exits.
192 @itemx @option{--version}
193 Prints a brief message listing @pspp{}'s version, warranties you don't
194 have, copying conditions and copyright, and e-mail address for bug
198 @itemx @option{--safer}
199 Disables certain unsafe operations. This includes the @subcmd{ERASE} and
200 @subcmd{HOST} commands, as well as use of pipes as input and output files.
202 @item @option{--testing-mode}
203 Invoke heuristics to assist with testing @pspp{}. For use
204 by @command{make check} and similar scripts.
207 @node PDF PostScript and SVG Output Options
208 @section PDF, PostScript, and SVG Output Options
213 To produce output in PDF, PostScript, and SVG formats, specify
214 @option{-o @var{file}} on the @pspp{} command line, optionally followed
215 by any of the options shown in the table below to customize the output
218 PDF, PostScript, and SVG output is only available if your installation
219 of @pspp{} was compiled with the Cairo library.
222 @item @option{-O format=@{pdf|ps|svg@}}
223 Specify the output format. This is only necessary if the file name
224 given on @option{-o} does not end in @file{.pdf}, @file{.ps}, or
227 @item @option{-O paper-size=@var{paper-size}}
228 Paper size, as a name (e.g.@: @code{a4}, @code{letter}) or
229 measurements (e.g.@: @code{210x297}, @code{8.5x11in}).
231 The default paper size is taken from the @env{PAPERSIZE} environment
232 variable or the file indicated by the @env{PAPERCONF} environment
233 variable, if either variable is set. If not, and your system supports
234 the @code{LC_PAPER} locale category, then the default paper size is
235 taken from the locale. Otherwise, if @file{/etc/papersize} exists,
236 the default paper size is read from it. As a last resort, A4 paper is
239 @item @option{-O foreground-color=@var{color}}
240 @itemx @option{-O background-color=@var{color}}
241 Sets @var{color} as the color to be used for the background or foreground.
242 Color should be given in the format @code{#@var{RRRR}@var{GGGG}@var{BBBB}},
243 where @var{RRRR}, @var{GGGG} and @var{BBBB} are 4 character hexadecimal
244 representations of the red, green and blue components respectively.
246 @item @option{-O orientation=@var{orientation}}
247 Either @code{portrait} or @code{landscape}. Default: @code{portrait}.
249 @item @option{-O left-margin=@var{dimension}}
250 @itemx @option{-O right-margin=@var{dimension}}
251 @itemx @option{-O top-margin=@var{dimension}}
252 @itemx @option{-O bottom-margin=@var{dimension}}
253 Sets the margins around the page. See
254 below for the allowed forms of @var{dimension} Default: @code{0.5in}.
256 @item @option{-O prop-font=@var{font-name}}
257 @itemx @option{-O emph-font=@var{font-name}}
258 @itemx @option{-O fixed-font=@var{font-name}}
259 Sets the font used for proportional, emphasized, or fixed-pitch text.
260 Most 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}, emphasis font @code{serif
265 italic}, fixed-pitch font @code{monospace}.
267 @item @option{-O font-size=@var{font-size}}
268 Sets the size of the default fonts, in thousandths of a point. Default:
271 @item @option{-O line-gutter=@var{dimension}}
272 Sets the width of white space on either side of lines that border text
273 or graphics objects. Default: @code{1pt}.
275 @item @option{-O line-spacing=@var{dimension}}
276 Sets the spacing between the lines in a double line in a table.
279 @item @option{-O line-width=@var{dimension}}
280 Sets the width of the lines used in tables. Default: @code{0.5pt}.
283 Each @var{dimension} value above may be specified in various units
284 based on its suffix: @samp{mm} for millimeters, @samp{in} for inches,
285 or @samp{pt} for points. Lacking a suffix, numbers below 50 are
286 assumed to be in inches and those about 50 are assumed to be in
289 @node Plain Text Output Options
290 @section Plain Text Output Options
292 @pspp{} can produce plain text output, drawing boxes using ASCII or
293 Unicode line drawing characters. To produce plain text output,
294 specify @option{-o @var{file}} on the @pspp{} command line, optionally
295 followed by options from the table below to customize the output
298 Plain text output is encoded in UTF-8.
301 @item @option{-O format=txt}
302 Specify the output format. This is only necessary if the file name
303 given on @option{-o} does not end in @file{.txt} or @file{.list}.
305 @item @option{-O charts=@{@var{template}.png|none@}}
306 Name for chart files included in output. The value should be a file
307 name that includes a single @samp{#} and ends in @file{png}. When a
308 chart is output, the @samp{#} is replaced by the chart number. The
309 default is the file name specified on @option{-o} with the extension
310 stripped off and replaced by @file{-#.png}.
312 Specify @code{none} to disable chart output. Charts are always
313 disabled if your installation of @pspp{} was compiled without the
316 @item @option{-O foreground-color=@var{color}}
317 @itemx @option{-O background-color=@var{color}}
318 Sets @var{color} as the color to be used for the background or foreground to
320 Color should be given in the format @code{#@var{RRRR}@var{GGGG}@var{BBBB}},
321 where @var{RRRR}, @var{GGGG} and @var{BBBB} are 4 character hexadecimal
322 representations of the red, green and blue components respectively.
323 If charts are disabled, this option has no effect.
325 @item @option{-O width=@var{columns}}
326 Width of a page, in columns. If unspecified or given as @code{auto},
327 the default is the width of the terminal, for interactive output, or
328 the WIDTH setting (@pxref{SET}), for output to a file.
330 @item @option{-O box=@{ascii|unicode@}}
331 Sets the characters used for lines in tables.
333 @code{ascii} the characters @samp{-}, @samp{|}, and @samp{+} for single-width
334 lines and @samp{=} and @samp{#} for double-width lines are used.
335 If set to @code{unicode} then Unicode box drawing characters will be used.
336 The default is @code{unicode} if the locale's character encoding is "UTF-8"
337 or @code{ascii} otherwise.
339 @item @option{-O emphasis=@{none|bold|underline@}}
340 How to emphasize text. Bold and underline emphasis are achieved with
341 overstriking, which may not be supported by all the software to which
342 you might pass the output. Default: @code{none}.
345 @node HTML Output Options
346 @section HTML Output Options
348 To produce output in HTML format, specify @option{-o @var{file}} on
349 the @pspp{} command line, optionally followed by any of the options shown
350 in the table below to customize the output format.
353 @item @option{-O format=html}
354 Specify the output format. This is only necessary if the file name
355 given on @option{-o} does not end in @file{.html}.
357 @item @option{-O charts=@{@var{template}.png|none@}}
358 Sets the name used for chart files. @xref{Plain Text Output Options},
361 @item @option{-O borders=@var{boolean}}
362 Decorate the tables with borders. If set to false, the tables produced
363 will have no borders. The default value is true.
365 @item @option{-O css=@var{boolean}}
366 Use cascading style sheets. Cascading style sheets give an improved appearance
367 and can be used to produce pages which fit a certain web site's style.
368 The default value is true.
372 @node OpenDocument Output Options
373 @section OpenDocument Output Options
375 To produce output as an OpenDocument text (ODT) document, specify
376 @option{-o @var{file}} on the @pspp{} command line. If @var{file} does
377 not end in @file{.odt}, you must also specify @option{-O format=odt}.
379 ODT support is only available if your installation of @pspp{} was
380 compiled with the libxml2 library.
382 The OpenDocument output format does not have any configurable options.
384 @node Comma-Separated Value Output Options
385 @section Comma-Separated Value Output Options
387 To produce output in comma-separated value (CSV) format, specify
388 @option{-o @var{file}} on the @pspp{} command line, optionally followed
389 by any of the options shown in the table below to customize the output
393 @item @option{-O format=csv}
394 Specify the output format. This is only necessary if the file name
395 given on @option{-o} does not end in @file{.csv}.
397 @item @option{-O separator=@var{field-separator}}
398 Sets the character used to separate fields. Default: a comma
401 @item @option{-O quote=@var{qualifier}}
402 Sets @var{qualifier} as the character used to quote fields that
403 contain white space, the separator (or any of the characters in the
404 separator, if it contains more than one character), or the quote
405 character itself. If @var{qualifier} is longer than one character,
406 only the first character is used; if @var{qualifier} is the empty
407 string, then fields are never quoted.
409 @item @option{-O titles=@var{boolean}}
410 Whether table titles (brief descriptions) should be printed. Default:
413 @item @option{-O captions=@var{boolean}}
414 Whether table captions (more extensive descriptions) should be
415 printed. Default: on.
418 The CSV format used is an extension to that specified in RFC 4180:
422 Each table row is output on a separate line, and each column is output
423 as a field. The contents of a cell that spans multiple rows or
424 columns is output only for the top-left row and column; the rest are
425 output as empty fields.
428 When a table has a title and titles are enabled, the title is output
429 just above the table as a single field prefixed by @samp{Table:}.
432 When a table has a caption and captions are enabled, the caption is
433 output just below the table as a single field prefixed by
437 Within a table, footnote markers are output as bracketed letters
438 following the cell's contents, e.g.@tie{}@samp{[a]}, @samp{[b]},
439 @enddots{} The footnotes themselves are output following the body of
440 the table, as a separate two-column table introduced with a line that
441 says @samp{Footnotes:}. Each row in the table represent one footnote:
442 the first column is the marker, the second column is the text.
445 Text in output is printed as a field on a line by itself. The TITLE
446 and SUBTITLE produce similar output, prefixed by @samp{Title:} or
447 @samp{Subtitle:}, respectively.
450 Errors, warnings, and notes are printed the same way as text.
453 Charts are not included in CSV output.
456 Successive output items are separated by a blank line.
458 @node Invoking PSPPIRE
459 @chapter Invoking @command{psppire}
460 @section The graphic user interface
461 @cindex Graphic user interface
464 The PSPPIRE graphic user interface for @pspp{} can perform all
465 functionality of the command line interface. In addition it gives an
466 instantaneous view of the data, variables and statistical output.
468 The graphic user interface can be started by typing @command{psppire} at a
470 Alternatively many systems have a system of interactive menus or buttons
471 from which @command{psppire} can be started by a series of mouse clicks.
473 Once the principles of the @pspp{} system are understood,
474 the graphic user interface is designed to be largely intuitive, and
475 for this reason is covered only very briefly by this manual.