docs

[pspp] / doc / invoking.texi

diff --git a/doc/invoking.texi b/doc/invoking.texi
index 24259a5808e2d0a101fbaf4acc58a1264319c334..3044efd48b113182802ef15c3dc882b47d86b415 100644 (file)
--- 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
 @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
 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
 @end menu
 
 @node Main Options


@@ -42,6 +52,7 @@ corresponding short options.
 -O format=@var{format}
 -O device=@{terminal|listing@}
 --no-output
 -O format=@var{format}
 -O device=@{terminal|listing@}
 --no-output

+--table-look=@var{file}

 -e, --error-file=@var{error-file}
 @end example
 
 -e, --error-file=@var{error-file}
 @end example
 


@@ -88,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
 
 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
 
 @item @option{-O @var{option}=@var{value}}
 Sets an option for the output file configured by a preceding


@@ -98,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
 @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.
 
 write HTML to a file named @file{pspp.out}.  Use @option{--help} to
 list the available formats.
 


@@ -115,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.
 
 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
 @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


@@ -148,7 +176,9 @@ interactive mode, respectively, rather than the default ``auto'' mode.
 
 @item @option{-r}
 @itemx @option{--no-statrc}
 
 @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@}}
 
 @item @option{-a @{enhanced|compatible@}}
 @itemx @option{--algorithm=@{enhanced|compatible@}}


@@ -193,29 +223,44 @@ Invoke heuristics to assist with testing @pspp{}.  For use
 by @command{make check} and similar scripts.
 @end table
 
 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 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
 
 @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
 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}}
 
 @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
 
 The default paper size is taken from the @env{PAPERSIZE} environment
 variable or the file indicated by the @env{PAPERCONF} environment


@@ -226,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}}
 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}.
 
 @item @option{-O orientation=@var{orientation}}
 Either @code{portrait} or @code{landscape}.  Default: @code{portrait}.


@@ -243,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}}
 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 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
 
 @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
 
 @node Plain Text Output Options
 @section Plain Text Output Options
 


@@ -298,45 +342,30 @@ 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}.
 
 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 paginate=@var{boolean}}
-If set, @pspp{} writes an ASCII formfeed the end of every page.  Default:
-@code{off}.
+Specify @code{none} to disable chart output.

 
 

-@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 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 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@}}
 
 @item @option{-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.
+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
 
 @item @option{-O emphasis=@{none|bold|underline@}}
 How to emphasize text.  Bold and underline emphasis are achieved with


@@ -344,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
 
 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
 @node HTML Output Options
 @section HTML Output Options
 @cindex HTML


@@ -364,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.
 
 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.
 @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.


@@ -408,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.
 
 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}}
 @item @option{-O captions=@var{boolean}}

-Whether table captions should be printed.  Default: @code{on}.
+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:
 @end table
 
 The CSV format used is an extension to that specified in RFC 4180:


@@ -419,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
 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
 
 @item Text
 Text in output is printed as a field on a line by itself.  The TITLE


@@ -447,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.
 
 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.
 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.
 
 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.
 the graphic user interface is designed to be largely intuitive, and
 for this reason is covered only very briefly by this manual.