work on PRINT encoding
[pspp] / doc / invoking.texi
index 3052162fddbfac4af381b3e3e1966c7f3e0704f8..f327b1cc5ee15916d1b82c7cb27741cbda24a20e 100644 (file)
-@node Invocation
-
-@chapter Starting PSPP
+@node Invoking PSPP
+@chapter Invoking @command{pspp}
 @cindex invocation
 @cindex invocation
-@cindex PSPP, invoking
-
-There are two separate user interfaces for PSPP.
-There is the command line interface, which responds to commands
-typed by the user.
-The command line interface is generally available on more platforms
-than the graphic user interface and since it doesn't require a
-graphics device it can be used from a remote terminal.
-Platforms which have a windowing system may also be able to support
-the graphic user interface.
-The graphic user interface can perform all functionality of the
-command line interface.
-In addition it gives an instantaneous view of the data, variables and
-statistical output.
+@cindex @pspp{}, invoking
 
 
-Whichever interface you choose, a basic understanding of the concepts
-used by PSPP is necessary before effective use of the system can be achieved.
+@pspp{} has two separate user interfaces.  This chapter describes
+@command{pspp}, @pspp{}'s command-line driven text-based user interface.
+The following chapter briefly describes PSPPIRE, the graphical user
+interface to @pspp{}.
 
 
+The sections below describe the @command{pspp} program's command-line
+interface.
 
 @menu
 
 @menu
-* The command line user interface::  
-* The graphic user interface::  
+* Main Options::                
+* PDF PostScript and SVG Output Options::  
+* Plain Text Output Options::   
+* HTML Output Options::         
+* OpenDocument Output Options::  
+* Comma-Separated Value Output Options::  
 @end menu
 
 @end menu
 
+@node Main Options
+@section Main Options
 
 
-@node The command line user interface
-@section The command line user interface
+Here is a summary of all the options, grouped by type, followed by
+explanations in the same order.
 
 
-@cindex command line, options
-@cindex options, command-line
+In the table, arguments to long options also apply to any
+corresponding short options.
 
 
+@table @emph
+@item Non-option arguments
 @example
 @example
-pspp [ -B @var{dir} | --config-dir=@var{dir} ] [ -o @var{device} | --device=@var{device} ]
-       [ -a @{compatible|enhanced@} | --algorithm=@{compatible|enhanced@}]
-       [ -x @{compatible|enhanced@} | --syntax=@{compatible|enhanced@}]
-       [ -I- | --no-include ]
-       [ -I @var{dir} | --include=@var{dir} ] [ -i | --interactive ] 
-       [ -r | --no-statrc ] [ -h | --help ] [ -l | --list ] 
-       [ -s | --safer ]
-       [ --testing-mode ] [ -V | --version ] [ -v | --verbose ] 
-       [ @var{key}=@var{value} ] @var{file}@enddots{}
+@var{syntax-file}
 @end example
 
 @end example
 
-@menu
-* Non-option Arguments::        Specifying syntax files and output devices.
-* Configuration Options::       Change the configuration for the current run.
-* Input and output options::    Controlling input and output files.
-* Language control options::    Language variants.
-* Informational options::       Helpful information about PSPP.
-@end menu
-
-@node Non-option Arguments
-@subsection Non-option Arguments
-
-Syntax files and output device substitutions can be specified on
-PSPP's command line:
-
-@table @code
-@item @var{file}
-
-A file by itself on the command line will be executed as a syntax file.
-If multiple files are specified, they are executed in order, as if
-their contents had been given in a single file.
-PSPP terminates after the syntax files run, unless the @code{-i} or
-@code{--interactive} option is given (@pxref{Language control options}).
-
-@item @var{key}=@var{value}
-
-Defines an output device macro @var{key} to expand to @var{value},
-overriding any macro having the same @var{key} defined in the device
-configuration file.  @xref{Macro definitions}.
-
-@end table
-
-There is one other way to specify a syntax file, if your operating
-system supports it.  If you have a syntax file @file{foobar.stat}, put
-the notation
-
+@item Output options
 @example
 @example
-#! /usr/local/bin/pspp
+-o, --output=@var{output-file}
+-O @var{option}=@var{value}
+-O format=@var{format}
+-O device=@{terminal|listing@}
+--no-output
+-e, --error-file=@var{error-file}
 @end example
 
 @end example
 
-at the top, and mark the file as executable with @code{chmod +x
-foobar.stat}.  (If PSPP is not installed in @file{/usr/local/bin},
-then insert its actual installation directory into the syntax file
-instead.)  Now you should be able to invoke the syntax file just by
-typing its name.  You can include any options on the command line as
-usual.  PSPP entirely ignores any lines beginning with @samp{#!}.
-
-@node Configuration Options
-@subsection Configuration Options
-
-Configuration options are used to change PSPP's configuration for the
-current run.  The configuration options are:
-
-@table @code
-@item -a @{compatible|enhanced@}
-@itemx --algorithm=@{compatible|enhanced@}
-
-If you chose @code{compatible}, then PSPP will use the same  algorithms 
-as used by some proprietary statistical analysis packages.
-This is not recommended, as  these algorithms are inferior and in some cases 
-compeletely broken.
-The default setting is @code{enhanced}.
-Certain commands have subcommands which allow you to override this setting on 
-a per command basis.
-
-@item -B @var{dir}
-@itemx --config-dir=@var{dir}
-
-Sets the configuration directory to @var{dir}.  @xref{File locations}.
+@item Language options
+@example
+-I, --include=@var{dir}
+-I-, --no-include
+-b, --batch
+-i, --interactive
+-r, --no-statrc
+-a, --algorithm=@{compatible|enhanced@}
+-x, --syntax=@{compatible|enhanced@}
+--syntax-encoding=@var{encoding}
+@end example
 
 
-@item -o @var{device}
-@itemx --device=@var{device}
+@item Informational options
+@example
+-h, --help
+-V, --version
+@end example
 
 
-Selects the output device with name @var{device}.  If this option is
-given more than once, then all devices mentioned are selected.  This
-option disables all devices besides those mentioned on the command line.
+@item Other options
+@example
+-s, --safer
+--testing-mode
+@end example
 @end table
 
 @end table
 
-@node Input and output options
-@subsection Input and output options
-
-Input and output options affect how PSPP reads input and writes
-output.  These are the input and output options:
-
-@table @code
-@item -I-
-@itemx --no-include
-
-Clears all directories from the include path.  This includes all
-directories put in the include path by default.  @xref{Miscellaneous
-configuring}.
-
-@item -I @var{dir}
-@itemx --include=@var{dir}
-
-Appends directory @var{dir} to the path that is searched for include
-files in PSPP syntax files.
+@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
+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 @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
+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.
+
+@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 @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
+write HTML to a file named @file{pspp.out}.  Use @option{--help} to
+list the available formats.
+
+@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
+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 @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 @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
+absence of these options, but this is suppressed if an output device
+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 @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 @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 @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 @option{-r}
+@itemx @option{--no-statrc}
+Disables running @file{rc} at @pspp{} startup time.
+
+@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
+the same results as the proprietary program SPSS.
+
+Some commands have subcommands that override this setting on a per
+command basis.
+
+@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 @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 @option{--help}
+Prints a message describing @pspp{} command-line syntax and the available
+device formats, then exits.
+
+@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 --testing-mode
+@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.
 
 
-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
 
 @end table
 
-@node Language control options
-@subsection Language control options
+@node PDF PostScript and SVG Output Options
+@section PDF, PostScript, and SVG Output Options
+@cindex PDF
+@cindex Postscript
+@cindex SVG
 
 
-Language control options control how PSPP syntax files are parsed and
-interpreted.  The available language control options are:
+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.
 
 
-@table @code
-@item -i
-@itemx --interactive
+PDF, PostScript, and SVG output is only available if your installation
+of @pspp{} was compiled with the Cairo library.
 
 
-When a syntax file is specified on the command line, PSPP normally
-terminates after processing it.  Giving this option will cause PSPP to
-bring up a command prompt after processing the syntax file.
+@table @asis
+@item @option{-O format=@{pdf|ps|svg@}}
+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}.
+
+@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}).
+
+The default paper size is taken from the @env{PAPERSIZE} environment
+variable or the file indicated by the @env{PAPERCONF} environment
+variable, if either variable is set.  If not, and your system supports
+the @code{LC_PAPER} locale category, then the default paper size is
+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 @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.
+
+@item @option{-O orientation=@var{orientation}}
+Either @code{portrait} or @code{landscape}.  Default: @code{portrait}.
+
+@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 @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.
+
+Default: proportional font @code{serif}, emphasis font @code{serif
+italic}, fixed-pitch font @code{monospace}.
+
+@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}.
+@end table
 
 
-In addition, this forces syntax files to be interpreted in interactive
-mode, rather than the default batch mode.  @xref{Tokenizing lines}, for
-information on the differences between batch mode and interactive mode
-command interpretation.
+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.
 
 
-@item -r
-@itemx --no-statrc
+@node Plain Text Output Options
+@section Plain Text Output Options
 
 
-Prevents the execution of the PSPP startup syntax file.
+@pspp{} can produce plain text output, drawing boxes using ASCII or
+Unicode line drawing characters.  To produce plain text output,
+specify @option{-o @var{file}} on the @pspp{} command line, optionally
+followed by options from the table below to customize the output
+format.
 
 
-@item -s
-@itemx --safer
+Plain text output is encoded in UTF-8.
 
 
-Disables certain unsafe operations.  This includes the ERASE and
-HOST commands, as well as use of pipes as input and output files.
+@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 @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 @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 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 @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
 
 @end table
 
-@node Informational options
-@subsection Informational options
-
-Informational options cause information about PSPP to be written to
-the terminal.  Here are the available options:
-
-@table @code
-@item -h
-@item --help
+@node HTML Output Options
+@section HTML Output Options
+@cindex HTML
+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.
 
 
-Prints a message describing PSPP command-line syntax and the available
-device driver classes, then terminates.
+@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 -l
-@item --list
+@item @option{-O charts=@{@var{template}.png|none@}}
+Sets the name used for chart files.  @xref{Plain Text Output Options},
+for details.
 
 
-Lists the available device driver classes, then terminates.
+@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 -x @{compatible|enhanced@}
-@itemx --syntax=@{compatible|enhanced@}
+@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.
 
 
-If you chose @code{compatible}, then PSPP will only accept command syntax that 
-is compatible with the proprietary program SPSS.
-If you choose @code{enhanced} then additional syntax will be available.
-The default is @code{enhanced}.
+@end table
 
 
+@node OpenDocument Output Options
+@section OpenDocument Output Options
 
 
-@item -V
-@item --version
+To produce output as an OpenDocument text (ODT) document, specify
+@option{-o @var{file}} on the @pspp{} command line.  If @var{file} does
+not end in @file{.odt}, you must also specify @option{-O format=odt}.
 
 
-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 terminates.
+ODT support is only available if your installation of @pspp{} was
+compiled with the libxml2 library.
 
 
-@item -v
-@item --verbose
+The OpenDocument output format does not have any configurable options.
 
 
-Increments PSPP's verbosity level.  Higher verbosity levels cause
-PSPP to display greater amounts of information about what it is
-doing.  Often useful for debugging PSPP's configuration.  
+@node Comma-Separated Value Output Options
+@section Comma-Separated Value Output Options
 
 
-This option can be given multiple times to set the verbosity level to
-that value.  The default verbosity level is 0, in which no informational
-messages will be displayed.
-
-Higher verbosity levels cause messages to be displayed when the
-corresponding events take place.
+To produce output in comma-separated value (CSV) 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 @asis
 
 @table @asis
-@item 1
-
-Driver and subsystem initializations.
-
-@item 2
-
-Completion of driver initializations.  Beginning of driver closings.
-
-@item 3
-
-Completion of driver closings.
-
-@item 4
-
-Files searched for; success of searches.
-
-@item 5
-
-Individual directories included in file searches.
+@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 @option{-O separator=@var{field-separator}}
+Sets the character used to separate fields.  Default: a comma
+(@samp{,}).
+
+@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
+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 @option{-O captions=@var{boolean}}
+Whether table captions should be printed.  Default: @code{on}.
 @end table
 
 @end table
 
-Each verbosity level also includes messages from lower verbosity levels.
+The CSV format used is an extension to that specified in RFC 4180:
 
 
+@table @asis
+@item Tables
+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:}.
+
+@item Text
+Text in output is printed as a field on a line by itself.  The TITLE
+and SUBTITLE produce similar output, prefixed by @samp{Title:} or
+@samp{Subtitle:}, respectively.
+
+@item Messages
+Errors, warnings, and notes are printed the same way as text.
+
+@item Charts
+Charts are not included in CSV output.
 @end table
 
 @end table
 
+Successive output items are separated by a blank line.
 
 
-@node The graphic user interface
+@node Invoking PSPPIRE
+@chapter Invoking @command{psppire}
 @section The graphic user interface
 @section The graphic user interface
-
 @cindex Graphic user interface
 @cindex PSPPIRE
 
 @cindex Graphic user interface
 @cindex PSPPIRE
 
+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 
 command prompt.
 Alternatively many systems have a system of interactive menus or buttons 
 from which @command{psppire} can be started by a series of mouse clicks.
 
 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 
 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.