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=88d4c1258a3d23e8b379b58c18e205fe321ebcc6;hpb=facb4a1ad3c9e8b2cdf55824680eed2afb91aebe;p=pspp diff --git a/doc/invoking.texi b/doc/invoking.texi index 88d4c1258a..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; @@ -22,8 +22,9 @@ interface. @menu * Main Options:: -* PDF PostScript and SVG Output 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:: @@ -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,9 +342,7 @@ 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}} @@ -320,10 +353,10 @@ 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{character-count}} -Width of a page, in characters. 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 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. @@ -340,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 @@ -360,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. @@ -433,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: