1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490
|
@node Invoking PSPP
@chapter Invoking @command{pspp}
@cindex invocation
@cindex @pspp{}, invoking
@pspp{} has two separate user interfaces. This chapter describes
@command{pspp}, @pspp{}'s command-line driven text-based user interface.
The following chapter briefly describes PSPPIRE, the graphical user
interface to @pspp{}.
The sections below describe the @command{pspp} program's command-line
interface.
@menu
* Main Options::
* PDF PostScript and SVG Output Options::
* Plain Text Output Options::
* HTML Output Options::
* OpenDocument Output Options::
* Comma-Separated Value Output Options::
@end menu
@node Main Options
@section Main Options
Here is a summary of all the options, grouped by type, followed by
explanations in the same order.
In the table, arguments to long options also apply to any
corresponding short options.
@table @emph
@item Non-option arguments
@example
@var{syntax-file}
@end example
@item Output options
@example
-o, --output=@var{output-file}
-O @var{option}=@var{value}
-O format=@var{format}
-O device=@{terminal|listing@}
--no-output
-e, --error-file=@var{error-file}
@end example
@item Language options
@example
-I, --include=@var{dir}
-I-, --no-include
-b, --batch
-i, --interactive
-r, --no-statrc
-a, --algorithm=@{compatible|enhanced@}
-x, --syntax=@{compatible|enhanced@}
--syntax-encoding=@var{encoding}
@end example
@item Informational options
@example
-h, --help
-V, --version
@end example
@item Other options
@example
-s, --safer
--testing-mode
@end example
@end table
@table @asis
@item @var{syntax-file}
Read and execute the named syntax file. If no syntax files are
specified, @pspp{} prompts for commands. If any syntax files are
specified, @pspp{} by default exits after it runs them, but you may make
it prompt for commands by specifying @samp{-} as an additional syntax
file.
@item @option{-o @var{output-file}}
Write output to @var{output-file}. @pspp{} has several different output
drivers that support output in various formats (use @option{--help} to
list the available formats). Specify this option more than once to
produce multiple output files, presumably in different formats.
Use @samp{-} as @var{output-file} to write output to standard output.
If no @option{-o} option is used, then @pspp{} writes text and CSV
output to standard output and other kinds of output to whose name is
based on the format, e.g.@: @file{pspp.pdf} for PDF output.
@item @option{-O @var{option}=@var{value}}
Sets an option for the output file configured by a preceding
@option{-o}. Most options are specific to particular output formats.
A few options that apply generically are listed below.
@item @option{-O format=@var{format}}
@pspp{} uses the extension of the file name given on @option{-o} to
select an output format. Use this option to override this choice by
specifying an alternate format, e.g.@: @option{-o pspp.out -O html} to
write HTML to a file named @file{pspp.out}. Use @option{--help} to
list the available formats.
@item @option{-O device=@{terminal|listing@}}
Sets whether @pspp{} considers the output device configured by the
preceding @option{-o} to be a terminal or a listing device. This
affects what output will be sent to the device, as configured by the
SET command's output routing subcommands (@pxref{SET}). By default,
output written to standard output is considered a terminal device and
other output is considered a listing device.
@item @option{--no-output}
Disables output entirely, if neither @option{-o} nor @option{-O} is
also used. If one of those options is used, @option{--no-output} has
no effect.
@item @option{-e @var{error-file}}
@itemx @option{--error-file=@var{error-file}}
Configures a file to receive @pspp{} error, warning, and note messages in
plain text format. Use @samp{-} as @var{error-file} to write messages
to standard output. The default error file is standard output in the
absence of these options, but this is suppressed if an output device
writes to standard output (or another terminal), to avoid printing
every message twice. Use @samp{none} as @var{error-file} to
explicitly suppress the default.
@item @option{-I @var{dir}}
@itemx @option{--include=@var{dir}}
Appends @var{dir} to the set of directories searched by the @cmd{INCLUDE}
(@pxref{INCLUDE}) and @cmd{INSERT} (@pxref{INSERT}) commands.
@item @option{-I-}
@itemx @option{--no-include}
Clears all directories from the include path, including directories
inserted in the include path by default. The default include path is
@file{.} (the current directory), followed by @file{.pspp} in the
user's home directory, followed by @pspp{}'s system configuration
directory (usually @file{/etc/pspp} or @file{/usr/local/etc/pspp}).
@item @option{-b}
@item @option{--batch}
@item @option{-i}
@itemx @option{--interactive}
These options forces syntax files to be interpreted in batch mode or
interactive mode, respectively, rather than the default ``auto'' mode.
@xref{Syntax Variants}, for a description of the differences.
@item @option{-r}
@itemx @option{--no-statrc}
Disables running @file{rc} at @pspp{} startup time.
@item @option{-a @{enhanced|compatible@}}
@itemx @option{--algorithm=@{enhanced|compatible@}}
With @code{enhanced}, the default, @pspp{} uses the best implemented
algorithms for statistical procedures. With @code{compatible},
however, @pspp{} will in some cases use inferior algorithms to produce
the same results as the proprietary program SPSS.
Some commands have subcommands that override this setting on a per
command basis.
@item @option{-x @{enhanced|compatible@}}
@itemx @option{--syntax=@{enhanced|compatible@}}
With @code{enhanced}, the default, @pspp{} accepts its own extensions
beyond those compatible with the proprietary program SPSS. With
@code{compatible}, @pspp{} rejects syntax that uses these extensions.
@item @option{--syntax-encoding=@var{encoding}}
Specifies @var{encoding} as the encoding for syntax files named on the
command line. The @var{encoding} also becomes the default encoding
for other syntax files read during the @pspp{} session by the
@cmd{INCLUDE} and @cmd{INSERT} commands. @xref{INSERT}, for the
accepted forms of @var{encoding}.
@item @option{--help}
Prints a message describing @pspp{} command-line syntax and the available
device formats, then exits.
@item @option{-V}
@itemx @option{--version}
Prints a brief message listing @pspp{}'s version, warranties you don't
have, copying conditions and copyright, and e-mail address for bug
reports, then exits.
@item @option{-s}
@itemx @option{--safer}
Disables certain unsafe operations. This includes the @subcmd{ERASE} and
@subcmd{HOST} commands, as well as use of pipes as input and output files.
@item @option{--testing-mode}
Invoke heuristics to assist with testing @pspp{}. For use
by @command{make check} and similar scripts.
@end table
@node PDF PostScript and SVG Output Options
@section PDF, PostScript, and SVG Output Options
@cindex PDF
@cindex Postscript
@cindex SVG
To produce output in PDF, PostScript, and SVG formats, specify
@option{-o @var{file}} on the @pspp{} command line, optionally followed
by any of the options shown in the table below to customize the output
format.
PDF, PostScript, and SVG output is only available if your installation
of @pspp{} was compiled with the Cairo library.
@table @asis
@item @option{-O format=@{pdf|ps|svg@}}
Specify the output format. This is only necessary if the file name
given on @option{-o} does not end in @file{.pdf}, @file{.ps}, or
@file{.svg}.
@item @option{-O paper-size=@var{paper-size}}
Paper size, as a name (e.g.@: @code{a4}, @code{letter}) or
measurements (e.g.@: @code{210x297}, @code{8.5x11in}).
The default paper size is taken from the @env{PAPERSIZE} environment
variable or the file indicated by the @env{PAPERCONF} environment
variable, if either variable is set. If not, and your system supports
the @code{LC_PAPER} locale category, then the default paper size is
taken from the locale. Otherwise, if @file{/etc/papersize} exists,
the default paper size is read from it. As a last resort, A4 paper is
assumed.
@item @option{-O foreground-color=@var{color}}
@itemx @option{-O background-color=@var{color}}
Sets @var{color} as the color to be used for the background or foreground.
Color should be given in the format @code{#@var{RRRR}@var{GGGG}@var{BBBB}},
where @var{RRRR}, @var{GGGG} and @var{BBBB} are 4 character hexadecimal
representations of the red, green and blue components respectively.
@item @option{-O orientation=@var{orientation}}
Either @code{portrait} or @code{landscape}. Default: @code{portrait}.
@item @option{-O left-margin=@var{dimension}}
@itemx @option{-O right-margin=@var{dimension}}
@itemx @option{-O top-margin=@var{dimension}}
@itemx @option{-O bottom-margin=@var{dimension}}
Sets the margins around the page. See
below for the allowed forms of @var{dimension} Default: @code{0.5in}.
@item @option{-O prop-font=@var{font-name}}
@itemx @option{-O emph-font=@var{font-name}}
@itemx @option{-O fixed-font=@var{font-name}}
Sets the font used for proportional, emphasized, or fixed-pitch text.
Most systems support CSS-like font names such as ``serif'' and
``monospace'', but a wide range of system-specific font are likely to
be supported as well.
Default: proportional font @code{serif}, emphasis font @code{serif
italic}, fixed-pitch font @code{monospace}.
@item @option{-O font-size=@var{font-size}}
Sets the size of the default fonts, in thousandths of a point. Default:
10000 (10 point).
@item @option{-O line-gutter=@var{dimension}}
Sets the width of white space on either side of lines that border text
or graphics objects. Default: @code{1pt}.
@item @option{-O line-spacing=@var{dimension}}
Sets the spacing between the lines in a double line in a table.
Default: @code{1pt}.
@item @option{-O line-width=@var{dimension}}
Sets the width of the lines used in tables. Default: @code{0.5pt}.
@end table
Each @var{dimension} value above may be specified in various units
based on its suffix: @samp{mm} for millimeters, @samp{in} for inches,
or @samp{pt} for points. Lacking a suffix, numbers below 50 are
assumed to be in inches and those about 50 are assumed to be in
millimeters.
@node Plain Text Output Options
@section Plain Text Output Options
@pspp{} can produce plain text output, drawing boxes using ASCII or
Unicode line drawing characters. To produce plain text output,
specify @option{-o @var{file}} on the @pspp{} command line, optionally
followed by options from the table below to customize the output
format.
Plain text output is encoded in UTF-8.
@table @asis
@item @option{-O format=txt}
Specify the output format. This is only necessary if the file name
given on @option{-o} does not end in @file{.txt} or @file{.list}.
@item @option{-O charts=@{@var{template}.png|none@}}
Name for chart files included in output. The value should be a file
name that includes a single @samp{#} and ends in @file{png}. When a
chart is output, the @samp{#} is replaced by the chart number. The
default is the file name specified on @option{-o} with the extension
stripped off and replaced by @file{-#.png}.
Specify @code{none} to disable chart output. Charts are always
disabled if your installation of @pspp{} was compiled without the
Cairo library.
@item @option{-O foreground-color=@var{color}}
@itemx @option{-O background-color=@var{color}}
Sets @var{color} as the color to be used for the background or foreground to
be used for charts.
Color should be given in the format @code{#@var{RRRR}@var{GGGG}@var{BBBB}},
where @var{RRRR}, @var{GGGG} and @var{BBBB} are 4 character hexadecimal
representations of the red, green and blue components respectively.
If charts are disabled, this option has no effect.
@item @option{-O paginate=@var{boolean}}
If set, @pspp{} writes an ASCII formfeed the end of every page. Default:
@code{off}.
@item @option{-O headers=@var{boolean}}
If enabled, @pspp{} prints two lines of header information giving title
and subtitle, page number, date and time, and @pspp{} version are printed
at the top of every page. These two lines are in addition to any top
margin requested. Default: @code{off}.
@item @option{-O length=@var{line-count}}
Physical length of a page. Headers and margins are subtracted from
this value. You may specify the number of lines as a number, or for
screen output you may specify @code{auto} to track the height of the
terminal as it changes. Default: @code{66}.
@item @option{-O width=@var{character-count}}
Width of a page, in characters. Margins are subtracted from this
value. For screen output you may specify @code{auto} in place of a
number to track the width of the terminal as it changes. Default:
@code{79}.
@item @option{-O top-margin=@var{top-margin-lines}}
Length of the top margin, in lines. @pspp{} subtracts this value from
the page length. Default: @code{0}.
@item @option{-O bottom-margin=@var{bottom-margin-lines}}
Length of the bottom margin, in lines. @pspp{} subtracts this value from
the page length. Default: @code{0}.
@item @option{-O box=@{ascii|unicode@}}
Sets the characters used for lines in tables.
If set to
@code{ascii} the characters @samp{-}, @samp{|}, and @samp{+} for single-width
lines and @samp{=} and @samp{#} for double-width lines are used.
If set to @code{unicode} then Unicode box drawing characters will be used.
The default is @code{unicode} if the locale's character encoding is "UTF-8"
or @code{ascii} otherwise.
@item @option{-O emphasis=@{none|bold|underline@}}
How to emphasize text. Bold and underline emphasis are achieved with
overstriking, which may not be supported by all the software to which
you might pass the output. Default: @code{none}.
@end table
@node HTML Output Options
@section HTML Output Options
@cindex HTML
To produce output in HTML format, specify @option{-o @var{file}} on
the @pspp{} command line, optionally followed by any of the options shown
in the table below to customize the output format.
@table @asis
@item @option{-O format=html}
Specify the output format. This is only necessary if the file name
given on @option{-o} does not end in @file{.html}.
@item @option{-O charts=@{@var{template}.png|none@}}
Sets the name used for chart files. @xref{Plain Text Output Options},
for details.
@item @option{-O borders=@var{boolean}}
Decorate the tables with borders. If set to false, the tables produced
will have no borders. The default value is true.
@item @option{-O css=@var{boolean}}
Use cascading style sheets. Cascading style sheets give an improved appearance
and can be used to produce pages which fit a certain web site's style.
The default value is true.
@end table
@node OpenDocument Output Options
@section OpenDocument Output Options
To produce output as an OpenDocument text (ODT) document, specify
@option{-o @var{file}} on the @pspp{} command line. If @var{file} does
not end in @file{.odt}, you must also specify @option{-O format=odt}.
ODT support is only available if your installation of @pspp{} was
compiled with the libxml2 library.
The OpenDocument output format does not have any configurable options.
@node Comma-Separated Value Output Options
@section Comma-Separated Value Output Options
To produce output in comma-separated value (CSV) format, specify
@option{-o @var{file}} on the @pspp{} command line, optionally followed
by any of the options shown in the table below to customize the output
format.
@table @asis
@item @option{-O format=csv}
Specify the output format. This is only necessary if the file name
given on @option{-o} does not end in @file{.csv}.
@item @option{-O separator=@var{field-separator}}
Sets the character used to separate fields. Default: a comma
(@samp{,}).
@item @option{-O quote=@var{qualifier}}
Sets @var{qualifier} as the character used to quote fields that
contain white space, the separator (or any of the characters in the
separator, if it contains more than one character), or the quote
character itself. If @var{qualifier} is longer than one character,
only the first character is used; if @var{qualifier} is the empty
string, then fields are never quoted.
@item @option{-O titles=@var{boolean}}
Whether table titles (brief descriptions) should be printed. Default:
@code{on}.
@item @option{-O captions=@var{boolean}}
Whether table captions (more extensive descriptions) should be
printed. Default: on.
@end table
The CSV format used is an extension to that specified in RFC 4180:
@table @asis
@item Tables
Each table row is output on a separate line, and each column is output
as a field. The contents of a cell that spans multiple rows or
columns is output only for the top-left row and column; the rest are
output as empty fields.
@item Titles
When a table has a title and titles are enabled, the title is output
just above the table as a single field prefixed by @samp{Table:}.
@item Captions
When a table has a caption and captions are enabled, the caption is
output just below the table as a single field prefixed by
@samp{Caption:}.
@item Footnotes
Within a table, footnote markers are output as bracketed letters
following the cell's contents, e.g.@tie{}@samp{[a]}, @samp{[b]},
@enddots{} The footnotes themselves are output following the body of
the table, as a separate two-column table introduced with a line that
says @samp{Footnotes:}. Each row in the table represent one footnote:
the first column is the marker, the second column is the text.
@item Text
Text in output is printed as a field on a line by itself. The TITLE
and SUBTITLE produce similar output, prefixed by @samp{Title:} or
@samp{Subtitle:}, respectively.
@item Messages
Errors, warnings, and notes are printed the same way as text.
@item Charts
Charts are not included in CSV output.
@end table
Successive output items are separated by a blank line.
@node Invoking PSPPIRE
@chapter Invoking @command{psppire}
@section The graphic user interface
@cindex Graphic user interface
@cindex PSPPIRE
The PSPPIRE graphic user interface for @pspp{} can perform all
functionality of the command line interface. In addition it gives an
instantaneous view of the data, variables and statistical output.
The graphic user interface can be started by typing @command{psppire} at a
command prompt.
Alternatively many systems have a system of interactive menus or buttons
from which @command{psppire} can be started by a series of mouse clicks.
Once the principles of the @pspp{} system are understood,
the graphic user interface is designed to be largely intuitive, and
for this reason is covered only very briefly by this manual.
|