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=bc53ae4dda457200180c13b5ed2f1d664856b057;hpb=5dbf5abcbed01f04422d4dead1c0ae0bb7efde4f;p=pspp diff --git a/doc/invoking.texi b/doc/invoking.texi index bc53ae4dda..3044efd48b 100644 --- a/doc/invoking.texi +++ b/doc/invoking.texi @@ -1,5 +1,5 @@ @c PSPP - a program for statistical analysis. -@c Copyright (C) 2017 Free Software Foundation, Inc. +@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; @@ -21,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 @@ -51,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 @@ -97,7 +99,7 @@ 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. +based on the format, @i{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 @@ -107,7 +109,7 @@ 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 +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. @@ -124,6 +126,23 @@ 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{--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 @@ -157,7 +176,9 @@ interactive mode, respectively, rather than the default ``auto'' mode. @item @option{-r} @itemx @option{--no-statrc} -Disables running @file{rc} at @pspp{} startup time. +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 @option{-a @{enhanced|compatible@}} @itemx @option{--algorithm=@{enhanced|compatible@}} @@ -202,29 +223,44 @@ 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 - -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. +@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. @table @asis -@item @option{-O format=@{pdf|ps|svg@}} +@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 @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}). +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 @@ -235,11 +271,9 @@ 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. +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 @option{-O orientation=@var{orientation}} Either @code{portrait} or @code{landscape}. Default: @code{portrait}. @@ -252,38 +286,39 @@ 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. +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 @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}. +@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 @@ -307,53 +342,25 @@ 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. +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 +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 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 +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. @@ -366,6 +373,21 @@ 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 @@ -386,6 +408,11 @@ for details. Decorate the tables with borders. If set to false, the tables produced will have no borders. The default value is true. +@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. @@ -459,7 +486,7 @@ output just below the table as a single field prefixed by @item Footnotes Within a table, footnote markers are output as bracketed letters -following the cell's contents, e.g.@tie{}@samp{[a]}, @samp{[b]}, +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: @@ -489,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.