X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Finvoking.texi;h=3044efd48b113182802ef15c3dc882b47d86b415;hb=refs%2Fheads%2Fctables7;hp=14b1ad0bedf23aea92102b996f9c14cc40eaca6b;hpb=1b1837591924226078c96db15888b68beec2ef6d;p=pspp diff --git a/doc/invoking.texi b/doc/invoking.texi index 14b1ad0bed..3044efd48b 100644 --- a/doc/invoking.texi +++ b/doc/invoking.texi @@ -1,3 +1,12 @@ +@c PSPP - a program for statistical analysis. +@c Copyright (C) 2017, 2020 Free Software Foundation, Inc. +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.3 +@c or any later version published by the Free Software Foundation; +@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +@c A copy of the license is included in the section entitled "GNU +@c Free Documentation License". +@c @node Invoking PSPP @chapter Invoking @command{pspp} @cindex invocation @@ -12,12 +21,13 @@ 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:: +* Main Options:: +* PDF PostScript SVG and PNG Output Options:: +* Plain Text Output Options:: +* TeX Output Options:: +* HTML Output Options:: +* OpenDocument Output Options:: +* Comma-Separated Value Output Options:: @end menu @node Main Options @@ -42,6 +52,7 @@ corresponding short options. -O format=@var{format} -O device=@{terminal|listing@} --no-output +--table-look=@var{file} -e, --error-file=@var{error-file} @end example @@ -70,7 +81,7 @@ corresponding short options. @end example @end table -@table @code +@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 @@ -78,7 +89,7 @@ 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 -o @var{output-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 @@ -86,22 +97,23 @@ 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 output to standard -output in plain text format. +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, @i{e.g.}@: @file{pspp.pdf} for PDF output. -@item -O @var{option}=@var{value} +@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 -O format=@var{format} +@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 +specifying an alternate format, @i{e.g.}@: @option{-o pspp.out -O format=html} to write HTML to a file named @file{pspp.out}. Use @option{--help} to list the available formats. -@item -O device=@{terminal|listing@} +@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 @@ -109,13 +121,30 @@ 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 --no-output +@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 -e @var{error-file} -@itemx --error-file=@var{error-file} +@item @option{--table-look=@var{file}} +Reads a table style from @var{file} and applies it to all @pspp{} +table output. The file should be a TableLook @file{.stt} or +@file{.tlo} file. @pspp{} searches for @var{file} in the current +directory, then in @file{.pspp/looks} in the user's home directory, +then in a @file{looks} subdirectory inside @pspp{}'s data directory +(usually @file{/usr/local/share/pspp}). If @pspp{} cannot find +@var{file} under the given name, it also tries adding a @file{.stt} +extension. + +When this option is not specified, @pspp{} looks for +@file{default.stt} using the algorithm above, and otherwise it falls +back to a default built-in style. + +Using @code{SET TLOOK} in @pspp{} syntax overrides the style set on +the command line (@pxref{SET}). + +@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 @@ -124,33 +153,35 @@ 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 -I @var{dir} -@itemx --include=@var{dir} -Appends @var{dir} to the set of directories searched by INCLUDE -(@pxref{INCLUDE}) and INSERT (@pxref{INSERT}). +@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 -I- -@itemx --no-include +@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 -b -@item --batch -@item -i -@itemx --interactive +@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 -r -@itemx --no-statrc -Disables running @file{rc} at @pspp{} startup time. +@item @option{-r} +@itemx @option{--no-statrc} +By default, at startup @pspp{} searches for a file named @file{rc} in +the include path (described above) and, if it finds one, runs the +commands in it. This option disables this behavior. -@item -a @{enhanced|compatible@} -@itemx --algorithm=@{enhanced|compatible@} +@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 @@ -159,62 +190,77 @@ the same results as the proprietary program SPSS. Some commands have subcommands that override this setting on a per command basis. -@item -x @{enhanced|compatible@} -@itemx --syntax=@{enhanced|compatible@} +@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 --syntax-encoding=@var{encoding} +@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 --help +@item @option{--help} Prints a message describing @pspp{} command-line syntax and the available device formats, then exits. -@item -V -@itemx --version +@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 -s -@itemx --safer -Disables certain unsafe operations. This includes the ERASE and -HOST commands, as well as use of pipes as input and output files. +@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 --testing-mode -Invoke heuristics to assist with testing @pspp{}. For use by @code{make -check} and similar scripts. +@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 +@node PDF PostScript SVG and PNG Output Options +@section PDF, PostScript, SVG, and PNG Output Options @cindex PDF @cindex Postscript @cindex SVG +@cindex PNG + +To produce output in PDF, PostScript, SVG, or PNG 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. + +PDF, PostScript, and SVG use real units: each dimension among the +options listed below may have a 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. + +PNG files are pixel-based, so dimensions in PNG output must ultimately +be measured in pixels. For output to these files, PSPP translates the +specified dimensions to pixels at 72 pixels per inch. For PNG output +only, fonts are by default rendered larger than this, at 96 pixels per +inch. + +An SVG or PNG file can only hold a single page. When PSPP outputs +more than one page to SVG or PNG, it creates multiple files. It +outputs the second page to a file named with a @code{-2} suffix, the +third with a @code{-3} suffix, and so on. -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 @code -@item -O format=@{pdf|ps|svg@} +@table @asis +@item @option{-O format=@{pdf|ps|svg|png@}} 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}. +given on @option{-o} does not end in @file{.pdf}, @file{.ps}, +@file{.svg}, or @file{.png}. -@item -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}). +@item @option{-O paper-size=@var{paper-size}} +Paper size, as a name (@i{e.g.}@: @code{a4}, @code{letter}) or +measurements (@i{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 @@ -224,56 +270,55 @@ 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 -O foreground-color=@var{color} -@itemx -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 foreground-color=@var{color}} +Sets @var{color} as the default color for lines and text. Use a CSS +color format (e.g.@: @code{#@var{rr}@var{gg}@var{bb}}) or name (e.g.@: +@code{black}) as @var{color}. -@item -O orientation=@var{orientation} +@item @option{-O orientation=@var{orientation}} Either @code{portrait} or @code{landscape}. Default: @code{portrait}. -@item -O left-margin=@var{dimension} -@itemx -O right-margin=@var{dimension} -@itemx -O top-margin=@var{dimension} -@itemx -O bottom-margin=@var{dimension} +@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 -O prop-font=@var{font-name} -@itemx -O emph-font=@var{font-name} -@itemx -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. +@item @option{-O prop-font=@var{font-name}} +Sets the default font used for ordinary text. Most systems support +CSS-like font names such as ``Sans Serif'', but a wide range of +system-specific fonts are likely to be supported as well. -Default: proportional font @code{serif}, emphasis font @code{serif -italic}, fixed-pitch font @code{monospace}. +Default: proportional font @code{Sans Serif}. -@item -O font-size=@var{font-size} +@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 -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 -O line-spacing=@var{dimension} -Sets the spacing between the lines in a double line in a table. -Default: @code{1pt}. - -@item -O line-width=@var{dimension} -Sets the width of the lines used in tables. Default: @code{0.5pt}. +@item @option{-O trim=true} +This option makes PSPP trim empty space around each page of output, +before adding the margins. This can make the output easier to include +in other documents. + +@item @option{-O outline=@var{boolean}} +For PDF output only, this option controls whether PSPP includes an +outline in the output file. PDF viewers usually display the outline +as a side bar that allows for easy navigation of the file. +The default is true unless @option{-O trim=true} is also specified. +(The Cairo graphics library that PSPP uses to produce PDF output has a +bug that can cause a crash when outlines and trimming are used +together.) + +@item @option{-O font-resolution=@var{dpi}} +Sets the resolution for font rendering, in dots per inch. For PDF, +PostScript, and SVG output, the default is 72 dpi, so that a 10-point +font is rendered with a height of 10 points. For PNG output, the +default is 96 dpi, so that a 10-point font is rendered with a height +of @math{10 / 72 * 96 = 13.3} pixels. Use a larger @var{dpi} to +enlarge text output, or a smaller @var{dpi} to shrink it. @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 @@ -285,64 +330,64 @@ format. Plain text output is encoded in UTF-8. -@table @code -@item -O format=txt +@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 -O charts=@{@var{template}.png|none@} +@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 -O paginate=@var{boolean} -If set, @pspp{} writes an ASCII formfeed the end of every page. Default: -@code{off}. - -@item -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 -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 -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 -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 -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 -O box=@{ascii|unicode@} -Sets the characters used for lines in tables. The default, -@code{ascii}, uses @samp{-}, @samp{|}, and @samp{+} for single-width -lines and @samp{=} and @samp{#} for double-width lines. Specify -@code{unicode} to use Unicode box drawing characters. - -@item -O emphasis=@{none|bold|underline@} +Specify @code{none} to disable chart output. + +@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 width=@var{columns}} +Width of a page, in columns. If unspecified or given as @code{auto}, +the default is the width of the terminal, for interactive output, or +the WIDTH setting (@pxref{SET}), for output to a file. + +@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 TeX Output Options +@section TeX Output Options +@cindex @TeX{} +@cindex tex + +If you want to publish statistical results in professional or academic +journals, you will probably want to provide results in @TeX{} format. +To do this, specify @option{-o @var{file}} on the @pspp{} command line where +@var{file} is a file name ending in @file{.tex}, or you can specify +@option{-O format=tex}. + +The resulting file can be directly processed using @TeX{} or you can manually +edit the file to add commentary text. +Alternatively, you can cut and paste desired sections to another @TeX{} file. + @node HTML Output Options @section HTML Output Options @cindex HTML @@ -350,20 +395,25 @@ 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 @code -@item -O format=html +@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 -O charts=@{@var{template}.png|none@} +@item @option{-O charts=@{@var{template}.png|none@}} Sets the name used for chart files. @xref{Plain Text Output Options}, for details. -@item -O borders=@var{boolean} +@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 -O css=@var{boolean} +@item @option{-O bare=@var{boolean}} +The HTML output driver ordinarily outputs a complete HTML document. +If set to true, the driver instead outputs only what would normally be +the contents of the @code{body} element. The default value is false. + +@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. @@ -390,16 +440,16 @@ To produce output in comma-separated value (CSV) format, specify by any of the options shown in the table below to customize the output format. -@table @code -@item -O format=csv +@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 -O separator=@var{field-separator} +@item @option{-O separator=@var{field-separator}} Sets the character used to separate fields. Default: a comma (@samp{,}). -@item -O quote=@var{qualifier} +@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 @@ -407,8 +457,13 @@ 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 -O captions=@var{boolean} -Whether table captions should be printed. Default: @code{on}. +@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: @@ -418,9 +473,24 @@ The CSV format used is an extension to that specified in RFC 4180: 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. When a table has a caption and captions are -enabled, the caption is output just above the table as a single field -prefixed by @samp{Table:}. +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, @i{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 @@ -446,11 +516,11 @@ 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 +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 +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, +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.