X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Finvoking.texi;h=3044efd48b113182802ef15c3dc882b47d86b415;hb=refs%2Fheads%2Fctables10;hp=d761935861c545f11d2fd9228d27d18fa2548b5b;hpb=fe76b9c2c49a0dd33aad5dfe3f03a056e6f96c21;p=pspp diff --git a/doc/invoking.texi b/doc/invoking.texi index d761935861..3044efd48b 100644 --- a/doc/invoking.texi +++ b/doc/invoking.texi @@ -1,227 +1,526 @@ -@node Invocation -@chapter Invoking PSPP +@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 -@cindex PSPP, invoking +@cindex @pspp{}, invoking -@cindex command line, options -@cindex options, command-line -@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{} -@end example +@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 -* 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. +* 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 Non-option Arguments -@section 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}). +@node Main Options +@section Main Options -@item @var{key}=@var{value} +Here is a summary of all the options, grouped by type, followed by +explanations in the same order. -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 +In the table, arguments to long options also apply to any +corresponding short options. +@table @emph +@item Non-option arguments @example -#! /usr/local/bin/pspp +@var{syntax-file} @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 -@section 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} +@item Output options +@example +-o, --output=@var{output-file} +-O @var{option}=@var{value} +-O format=@var{format} +-O device=@{terminal|listing@} +--no-output +--table-look=@var{file} +-e, --error-file=@var{error-file} +@end example -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 -@node Input and output options -@section 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 text and CSV +output to standard output and other kinds of output to whose name is +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 +@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, @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. + +@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{--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 +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} +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@}} +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 -@node Language control options -@section Language control options - -Language control options control how PSPP syntax files are parsed and -interpreted. The available language control options are: +@node PDF PostScript SVG and PNG Output Options +@section PDF, PostScript, SVG, and PNG Output Options +@cindex PDF +@cindex Postscript +@cindex SVG +@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 @code -@item -i -@itemx --interactive - -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. - -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. +@table @asis +@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}, +@file{.svg}, or @file{.png}. + +@item @option{-O paper-size=@var{paper-size}} +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 +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}} +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 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}} +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{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 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 -@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. + +@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 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 +@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 +overstriking, which may not be supported by all the software to which +you might pass the output. Default: @code{none}. @end table -@node Informational options -@section Informational options - -Informational options cause information about PSPP to be written to -the terminal. Here are the available options: +@node TeX Output Options +@section TeX Output Options +@cindex @TeX{} +@cindex tex -@table @code -@item -h -@item --help +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}. -Prints a message describing PSPP command-line syntax and the available -device driver classes, then terminates. +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. -@item -l -@item --list +@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. -Lists the available device driver classes, then terminates. - -@item -x @{compatible|enhanced@} -@itemx --syntax=@{compatible|enhanced@} - -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}. +@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 @option{-O charts=@{@var{template}.png|none@}} +Sets the name used for chart files. @xref{Plain Text Output Options}, +for details. -@item -V -@item --version +@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. -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. +@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 -v -@item --verbose +@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. -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. +@end table -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. +@node OpenDocument Output Options +@section OpenDocument Output Options -Higher verbosity levels cause messages to be displayed when the -corresponding events take place. +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}. -@table @asis -@item 1 +ODT support is only available if your installation of @pspp{} was +compiled with the libxml2 library. -Driver and subsystem initializations. +The OpenDocument output format does not have any configurable options. -@item 2 +@node Comma-Separated Value Output Options +@section Comma-Separated Value Output Options -Completion of driver initializations. Beginning of driver closings. +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. -@item 3 +@table @asis +@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 titles=@var{boolean}} +Whether table titles (brief descriptions) should be printed. Default: +@code{on}. + +@item @option{-O captions=@var{boolean}} +Whether table captions (more extensive descriptions) should be +printed. Default: on. +@end table -Completion of driver closings. +The CSV format used is an extension to that specified in RFC 4180: -@item 4 +@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. + +@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 +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 -Files searched for; success of searches. +Successive output items are separated by a blank line. -@item 5 +@node Invoking PSPPIRE +@chapter Invoking @command{psppire} +@section The graphic user interface +@cindex Graphic user interface +@cindex PSPPIRE -Individual directories included in file searches. -@end table +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. -Each verbosity level also includes messages from lower verbosity levels. +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. -@end table -@setfilename ignored +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.