2 @chapter Invoking @command{pspp}
6 PSPP has two separate user interfaces. This chapter describes
7 @command{pspp}, PSPP's command-line driven text-based user interface.
8 The following chapter briefly describes PSPPIRE, the graphical user
11 The sections below describe the @command{pspp} program's command-line
16 * PDF PostScript and SVG Output Options::
17 * Plain Text Output Options::
18 * HTML Output Options::
19 * OpenDocument Output Options::
20 * Comma-Separated Value Output Options::
26 Here is a summary of all the options, grouped by type, followed by
27 explanations in the same order.
29 In the table, arguments to long options also apply to any
30 corresponding short options.
33 @item Non-option arguments
40 -o, --output=@var{output-file}
41 -O @var{option}=@var{value}
42 -O format=@var{format}
43 -O device=@{terminal|listing@}
45 -e, --error-file=@var{error-file}
48 @item Language options
50 -I, --include=@var{dir}
55 -a, --algorithm=@{compatible|enhanced@}
56 -x, --syntax=@{compatible|enhanced@}
57 --syntax-encoding=@var{encoding}
60 @item Informational options
74 @item @var{syntax-file}
75 Read and execute the named syntax file. If no syntax files are
76 specified, PSPP prompts for commands. If any syntax files are
77 specified, PSPP by default exits after it runs them, but you may make
78 it prompt for commands by specifying @samp{-} as an additional syntax
81 @item -o @var{output-file}
82 Write output to @var{output-file}. PSPP has several different output
83 drivers that support output in various formats (use @option{--help} to
84 list the available formats). Specify this option more than once to
85 produce multiple output files, presumably in different formats.
87 Use @samp{-} as @var{output-file} to write output to standard output.
89 If no @option{-o} option is used, then PSPP writes output to standard
90 output in plain text format.
92 @item -O @var{option}=@var{value}
93 Sets an option for the output file configured by a preceding
94 @option{-o}. Most options are specific to particular output formats.
95 A few options that apply generically are listed below.
97 @item -O format=@var{format}
98 PSPP uses the extension of the file name given on @option{-o} to
99 select an output format. Use this option to override this choice by
100 specifying an alternate format, e.g.@: @option{-o pspp.out -O html} to
101 write HTML to a file named @file{pspp.out}. Use @option{--help} to
102 list the available formats.
104 @item -O device=@{terminal|listing@}
105 Sets whether PSPP considers the output device configured by the
106 preceding @option{-o} to be a terminal or a listing device. This
107 affects what output will be sent to the device, as configured by the
108 SET command's output routing subcommands (@pxref{SET}). By default,
109 output written to standard output is considered a terminal device and
110 other output is considered a listing device.
113 Disables output entirely, if neither @option{-o} nor @option{-O} is
114 also used. If one of those options is used, @option{--no-output} has
117 @item -e @var{error-file}
118 @itemx --error-file=@var{error-file}
119 Configures a file to receive PSPP error, warning, and note messages in
120 plain text format. Use @samp{-} as @var{error-file} to write messages
121 to standard output. The default error file is standard output in the
122 absence of these options, but this is suppressed if an output device
123 writes to standard output (or another terminal), to avoid printing
124 every message twice. Use @samp{none} as @var{error-file} to
125 explicitly suppress the default.
128 @itemx --include=@var{dir}
129 Appends @var{dir} to the set of directories searched by INCLUDE
130 (@pxref{INCLUDE}) and INSERT (@pxref{INSERT}).
134 Clears all directories from the include path, including directories
135 inserted in the include path by default. The default include path is
136 @file{.} (the current directory), followed by @file{.pspp} in the
137 user's home directory, followed by PSPP's system configuration
138 directory (usually @file{/etc/pspp} or @file{/usr/local/etc/pspp}).
144 These options forces syntax files to be interpreted in batch mode or
145 interactive mode, respectively, rather than the default ``auto'' mode.
146 @xref{Syntax Variants}, for a description of the differences.
150 Disables running @file{rc} at PSPP startup time.
152 @item -a @{enhanced|compatible@}
153 @itemx --algorithm=@{enhanced|compatible@}
154 With @code{enhanced}, the default, PSPP uses the best implemented
155 algorithms for statistical procedures. With @code{compatible},
156 however, PSPP will in some cases use inferior algorithms to produce
157 the same results as the proprietary program SPSS.
159 Some commands have subcommands that override this setting on a per
162 @item -x @{enhanced|compatible@}
163 @itemx --syntax=@{enhanced|compatible@}
164 With @code{enhanced}, the default, PSPP accepts its own extensions
165 beyond those compatible with the proprietary program SPSS. With
166 @code{compatible}, PSPP rejects syntax that uses these extensions.
168 @item --syntax-encoding=@var{encoding}
169 Specifies @var{encoding} as the encoding for syntax files named on the
170 command line. The @var{encoding} also becomes the default encoding
171 for other syntax files read during the PSPP session by the
172 @cmd{INCLUDE} and @cmd{INSERT} commands. @xref{INSERT}, for the
173 accepted forms of @var{encoding}.
176 Prints a message describing PSPP command-line syntax and the available
177 device formats, then exits.
181 Prints a brief message listing PSPP's version, warranties you don't
182 have, copying conditions and copyright, and e-mail address for bug
187 Disables certain unsafe operations. This includes the ERASE and
188 HOST commands, as well as use of pipes as input and output files.
191 Invoke heuristics to assist with testing PSPP. For use by @code{make
192 check} and similar scripts.
195 @node PDF PostScript and SVG Output Options
196 @section PDF, PostScript, and SVG Output Options
198 To produce output in PDF, PostScript, and SVG formats, specify
199 @option{-o @var{file}} on the PSPP command line, optionally followed
200 by any of the options shown in the table below to customize the output
203 PDF, PostScript, and SVG output is only available if your installation
204 of PSPP was compiled with the Cairo library.
207 @item -O format=@{pdf|ps|svg@}
208 Specify the output format. This is only necessary if the file name
209 given on @option{-o} does not end in @file{.pdf}, @file{.ps}, or
212 @item -O paper-size=@var{paper-size}
213 Paper size, as a name (e.g.@: @code{a4}, @code{letter}) or
214 measurements (e.g.@: @code{210x297}, @code{8.5x11in}).
216 The default paper size is taken from the @env{PAPERSIZE} environment
217 variable or the file indicated by the @env{PAPERCONF} environment
218 variable, if either variable is set. If not, and your system supports
219 the @code{LC_PAPER} locale category, then the default paper size is
220 taken from the locale. Otherwise, if @file{/etc/papersize} exists,
221 the default paper size is read from it. As a last resort, A4 paper is
224 @item -O orientation=@var{orientation}
225 Either @code{portrait} or @code{landscape}. Default: @code{portrait}.
227 @item -O left-margin=@var{dimension}
228 @itemx -O right-margin=@var{dimension}
229 @itemx -O top-margin=@var{dimension}
230 @itemx -O bottom-margin=@var{dimension}
231 Sets the margins around the page. See
232 below for the allowed forms of @var{dimension} Default: @code{0.5in}.
234 @item -O prop-font=@var{font-name}
235 @itemx -O emph-font=@var{font-name}
236 @itemx -O fixed-font=@var{font-name}
237 Sets the font used for proportional, emphasized, or fixed-pitch text.
238 Most systems support CSS-like font names such as ``serif'' and
239 ``monospace'', but a wide range of system-specific font are likely to
240 be supported as well.
242 Default: proportional font @code{serif}, emphasis font @code{serif
243 italic}, fixed-pitch font @code{monospace}.
245 @item -O font-size=@var{font-size}
246 Sets the size of the default fonts, in thousandths of a point. Default:
249 @item -O line-gutter=@var{dimension}
250 Sets the width of white space on either side of lines that border text
251 or graphics objects. Default: @code{1pt}.
253 @item -O line-spacing=@var{dimension}
254 Sets the spacing between the lines in a double line in a table.
257 @item -O line-width=@var{dimension}
258 Sets the width of the lines used in tables. Default: @code{0.5pt}.
261 Each @var{dimension} value above may be specified in various units
262 based on its suffix: @samp{mm} for millimeters, @samp{in} for inches,
263 or @samp{pt} for points. Lacking a suffix, numbers below 50 are
264 assumed to be in inches and those about 50 are assumed to be in
267 @node Plain Text Output Options
268 @section Plain Text Output Options
270 PSPP can produce plain text output, drawing boxes using ASCII or
271 Unicode line drawing characters. To produce plain text output,
272 specify @option{-o @var{file}} on the PSPP command line, optionally
273 followed by options from the table below to customize the output
278 Specify the output format. This is only necessary if the file name
279 given on @option{-o} does not end in @file{.txt} or @file{.list}.
281 @item -O charts=@{@var{template}.png|none@}
282 Name for chart files included in output. The value should be a file
283 name that includes a single @samp{#} and ends in @file{png}. When a
284 chart is output, the @samp{#} is replaced by the chart number. The
285 default is the file name specified on @option{-o} with the extension
286 stripped off and replaced by @file{-#.png}.
288 Specify @code{none} to disable chart output. Charts are always
289 disabled if your installation of PSPP was compiled without the
292 @item -O paginate=@var{boolean}
293 If set, PSPP writes an ASCII formfeed the end of every page. Default:
296 @item -O headers=@var{boolean}
297 If enabled, PSPP prints two lines of header information giving title
298 and subtitle, page number, date and time, and PSPP version are printed
299 at the top of every page. These two lines are in addition to any top
300 margin requested. Default: @code{off}.
302 @item -O length=@var{line-count}
303 Physical length of a page. Headers and margins are subtracted from
304 this value. You may specify the number of lines as a number, or for
305 screen output you may specify @code{auto} to track the height of the
306 terminal as it changes. Default: @code{66}.
308 @item -O width=@var{character-count}
309 Width of a page, in characters. Margins are subtracted from this
310 value. For screen output you may specify @code{auto} in place of a
311 number to track the width of the terminal as it changes. Default:
314 @item -O top-margin=@var{top-margin-lines}
315 Length of the top margin, in lines. PSPP subtracts this value from
316 the page length. Default: @code{0}.
318 @item -O bottom-margin=@var{bottom-margin-lines}
319 Length of the bottom margin, in lines. PSPP subtracts this value from
320 the page length. Default: @code{0}.
322 @item -O box[@var{line-type}]=@var{box-chars}
323 Sets the characters used for lines in tables. @var{line-type} is a
324 4-digit number that indicates the type of line to change, in the order
325 `right', `bottom', `left', `top'. Each digit is 0 for ``no line'', 1
326 for a single line, and 2 for a double line. @var{box-chars} is the
327 character or string of characters to use for this type of line.
329 For example, @code{box[0101]="|"} sets @samp{|} as the character to
330 use for a single-width vertical line, and @code{box[1100]="\xda"} sets
331 @samp{"\xda"}, which on MS-DOS is suitable for the top-left corner of
332 a box, as the character for the intersection of two single-width
333 lines, one each from the right and bottom.
335 The defaults use @samp{-}, @samp{|}, and @samp{+} for single-width
336 lines and @samp{=} and @samp{#} for double-width lines.
338 @item -O init=@var{init-string}
339 If set, this string is written at the beginning of each output file.
340 It can be used to initialize device features, e.g.@: to enable VT100
341 line-drawing characters.
343 @item -O emphasis=@{none|bold|underline@}
344 How to emphasize text. Bold and underline emphasis are achieved with
345 overstriking, which may not be supported by all the software to which
346 you might pass the output. Default: @code{none}.
349 @node HTML Output Options
350 @section HTML Output Options
352 To produce output in HTML format, specify @option{-o @var{file}} on
353 the PSPP command line, optionally followed by any of the options shown
354 in the table below to customize the output format.
358 Specify the output format. This is only necessary if the file name
359 given on @option{-o} does not end in @file{.html}.
361 @item -O charts=@{@var{template}.png|none@}
362 Sets the name used for chart files. @xref{Plain Text Output Options},
366 @node OpenDocument Output Options
367 @section OpenDocument Output Options
369 To produce output as an OpenDocument text (ODT) document, specify
370 @option{-o @var{file}} on the PSPP command line. If @var{file} does
371 not end in @file{.odt}, you must also specify @option{-O format=odt}.
373 ODT support is only available if your installation of PSPP was
374 compiled with the libxml2 library.
376 The OpenDocument output format does not have any configurable options.
378 @node Comma-Separated Value Output Options
379 @section Comma-Separated Value Output Options
381 To produce output in comma-separated value (CSV) format, specify
382 @option{-o @var{file}} on the PSPP command line, optionally followed
383 by any of the options shown in the table below to customize the output
388 Specify the output format. This is only necessary if the file name
389 given on @option{-o} does not end in @file{.csv}.
391 @item -O separator=@var{field-separator}
392 Sets the character used to separate fields. Default: a comma
395 @item -O quote=@var{qualifier}
396 Sets @var{qualifier} as the character used to quote fields that
397 contain white space, the separator (or any of the characters in the
398 separator, if it contains more than one character), or the quote
399 character itself. If @var{qualifier} is longer than one character,
400 only the first character is used; if @var{qualifier} is the empty
401 string, then fields are never quoted.
403 @item -O captions=@var{boolean}
404 Whether table captions should be printed. Default: @code{on}.
407 The CSV format used is an extension to that specified in RFC 4180:
411 Each table row is output on a separate line, and each column is output
412 as a field. The contents of a cell that spans multiple rows or
413 columns is output only for the top-left row and column; the rest are
414 output as empty fields. When a table has a caption and captions are
415 enabled, the caption is output just above the table as a single field
416 prefixed by @samp{Table:}.
419 Text in output is printed as a field on a line by itself. The TITLE
420 and SUBTITLE produce similar output, prefixed by @samp{Title:} or
421 @samp{Subtitle:}, respectively.
424 Errors, warnings, and notes are printed the same way as text.
427 Charts are not included in CSV output.
430 Successive output items are separated by a blank line.
432 @node Invoking PSPPIRE
433 @chapter Invoking @command{psppire}
434 @section The graphic user interface
435 @cindex Graphic user interface
438 The PSPPIRE graphic user interface for PSPP can perform all
439 functionality of the command line interface. In addition it gives an
440 instantaneous view of the data, variables and statistical output.
442 The graphic user interface can be started by typing @command{psppire} at a
444 Alternatively many systems have a system of interactive menus or buttons
445 from which @command{psppire} can be started by a series of mouse clicks.
447 Once the principles of the PSPP system are understood,
448 the graphic user interface is designed to be largely intuitive, and
449 for this reason is covered only very briefly by this manual.