X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Finvoking.texi;h=3044efd48b113182802ef15c3dc882b47d86b415;hb=f6c6ee97c412e47eb1c7c30adc224e93b6c1586a;hp=9590f093b887f8f6e1b53cca1f6bd6772a0e2d13;hpb=ac0b46916cf9c10ebe85bc51d83c9fb713903284;p=pspp diff --git a/doc/invoking.texi b/doc/invoking.texi index 9590f093b8..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,7 +22,7 @@ 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:: @@ -52,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 @@ -98,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 @@ -108,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 format=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. @@ -125,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 @@ -205,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 @@ -238,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}. @@ -255,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 @@ -310,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}} @@ -456,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: