Fix missing @clicksequence problem with older Texinfo versions.

[pspp-builds.git] / doc / language.texi

diff --git a/doc/language.texi b/doc/language.texi
index 7ce4d88938d03786c77fbc3f50ec3792e1850f0a..e23a558028805dbc9babcb360811d34c87258434 100644 (file)
--- a/doc/language.texi
+++ b/doc/language.texi
@@ -1,13 +1,11 @@
-@node Language, Expressions, Invocation, Top
+@node Language

 @chapter The PSPP language
 @cindex language, PSPP
 @cindex PSPP, language
 
 @chapter The PSPP language
 @cindex language, PSPP
 @cindex PSPP, language
 

-@quotation
-@strong{Please note:} PSPP is not even close to completion.
+@note{PSPP is not even close to completion.

 Only a few statistical procedures are implemented.  PSPP
 Only a few statistical procedures are implemented.  PSPP

-is a work in progress.
-@end quotation
+is a work in progress.}

 
 This chapter discusses elements common to many PSPP commands.
 Later chapters will describe individual commands in detail.
 
 This chapter discusses elements common to many PSPP commands.
 Later chapters will describe individual commands in detail.


@@ -15,6 +13,7 @@ Later chapters will describe individual commands in detail.
 @menu
 * Tokens::                      Characters combine to form tokens.
 * Commands::                    Tokens combine to form commands.
 @menu
 * Tokens::                      Characters combine to form tokens.
 * Commands::                    Tokens combine to form commands.

+* Syntax Variants::             Batch vs. Interactive mode

 * Types of Commands::           Commands come in several flavors.
 * Order of Commands::           Commands combine to form syntax files.
 * Missing Observations::        Handling missing observations.
 * Types of Commands::           Commands come in several flavors.
 * Order of Commands::           Commands combine to form syntax files.
 * Missing Observations::        Handling missing observations.


@@ -24,7 +23,8 @@ Later chapters will describe individual commands in detail.
 * BNF::                         How command syntax is described.
 @end menu
 
 * BNF::                         How command syntax is described.
 @end menu
 

-@node Tokens, Commands, Language, Language
+
+@node Tokens

 @section Tokens
 @cindex language, lexical analysis
 @cindex language, tokens
 @section Tokens
 @cindex language, lexical analysis
 @cindex language, tokens


@@ -159,7 +159,7 @@ doing so.  Throughout the remainder of this manual we will assume that
 the default setting is in effect.
 @end table
 
 the default setting is in effect.
 @end table
 

-@node Commands, Types of Commands, Tokens, Language
+@node Commands

 @section Forming commands of tokens
 
 @cindex PSPP, command structure
 @section Forming commands of tokens
 
 @cindex PSPP, command structure


@@ -188,17 +188,36 @@ one that consists only of white space or comments, also ends a command
 by default, although you can use the NULLINE subcommand of @cmd{SET}
 to disable this feature (@pxref{SET}).
 
 by default, although you can use the NULLINE subcommand of @cmd{SET}
 to disable this feature (@pxref{SET}).
 

-In batch mode only, that is, when reading commands from a file instead
-of an interactive user, any line that contains a non-space character
-in the leftmost column begins a new command.  Thus, each command
-consists of a flush-left line followed by any number of lines indented
-from the left margin.  In this mode, a plus or minus sign
-(@samp{+}, @samp{@minus{}}) as the first character
-in a line is ignored and causes that line to begin a new command,
-which allows for visual indentation of a command without that command
-being considered part of the previous command.
-
-@node Types of Commands, Order of Commands, Commands, Language
+@node Syntax Variants
+@section Variants of syntax.
+
+@cindex Batch syntax
+@cindex Interactive syntax
+
+There are two variants of command syntax, @i{viz}: @dfn{batch} mode and
+@dfn{interactive} mode.
+Batch mode is the default when reading commands from a file.
+Interactive mode is the default when commands are typed at a prompt
+by a user.
+Certain commands, such as @cmd{INSERT} (@pxref{INSERT}), may explicitly
+change the syntax mode. 
+
+In batch mode, any line that contains a non-space character
+in the leftmost column begins a new command. 
+Thus, each command consists of a flush-left line followed by any
+number of lines indented from the left margin. 
+In this mode, a plus or minus sign (@samp{+}, @samp{@minus{}}) as the
+first character in a line is ignored and causes that line to begin a
+new command, which allows for visual indentation of a command without
+that command being considered part of the previous command. 
+The period terminating the end of a command is optional but recommended.
+
+In interactive mode, each command must  either be terminated with a period,
+or an empty line must follow the command.
+The use of (@samp{+} and @samp{@minus{}} as continuation characters is not
+permitted.
+
+@node Types of Commands

 @section Types of Commands
 
 Commands in PSPP are divided roughly into six categories:
 @section Types of Commands
 
 Commands in PSPP are divided roughly into six categories:


@@ -241,7 +260,7 @@ more general sense, a @dfn{procedure} is any command that causes the
 active file (the data) to be read.
 @end table
 
 active file (the data) to be read.
 @end table
 

-@node Order of Commands, Missing Observations, Types of Commands, Language
+@node Order of Commands

 @section Order of Commands
 @cindex commands, ordering
 @cindex order of commands
 @section Order of Commands
 @cindex commands, ordering
 @cindex order of commands


@@ -339,7 +358,7 @@ Cause a transition to the procedure state.
 @end itemize
 @end table
 
 @end itemize
 @end table
 

-@node Missing Observations, Variables, Order of Commands, Language
+@node Missing Observations

 @section Handling missing observations
 @cindex missing values
 @cindex values, missing
 @section Handling missing observations
 @cindex missing values
 @cindex values, missing


@@ -360,16 +379,14 @@ spaces.
 Variables, whether numeric or string, can have designated
 @dfn{user-missing values}.  Every user-missing value is an actual value
 for that variable.  However, most of the time user-missing values are
 Variables, whether numeric or string, can have designated
 @dfn{user-missing values}.  Every user-missing value is an actual value
 for that variable.  However, most of the time user-missing values are

-treated in the same way as the system-missing value.  String variables
-that are wider than a certain width, usually 8 characters (depending on
-computer architecture), cannot have user-missing values.
+treated in the same way as the system-missing value.

 
 For more information on missing values, see the following sections:
 @ref{Variables}, @ref{MISSING VALUES}, @ref{Expressions}.  See also the
 documentation on individual procedures for information on how they
 handle missing values.
 
 
 For more information on missing values, see the following sections:
 @ref{Variables}, @ref{MISSING VALUES}, @ref{Expressions}.  See also the
 documentation on individual procedures for information on how they
 handle missing values.
 

-@node Variables, Files, Missing Observations, Language
+@node Variables

 @section Variables
 @cindex variables
 @cindex dictionary
 @section Variables
 @cindex variables
 @cindex dictionary


@@ -387,7 +404,7 @@ Some details of variables are described in the sections below.
 * Scratch Variables::           Variables deleted by procedures.
 @end menu
 
 * Scratch Variables::           Variables deleted by procedures.
 @end menu
 

-@node Attributes, System Variables, Variables, Variables
+@node Attributes

 @subsection Attributes of Variables
 @cindex variables, attributes of
 @cindex attributes of variables
 @subsection Attributes of Variables
 @cindex variables, attributes of
 @cindex attributes of variables


@@ -428,13 +445,9 @@ Numeric or string.
 @item Width
 (string variables only) String variables with a width of 8 characters or
 fewer are called @dfn{short string variables}.  Short string variables
 @item Width
 (string variables only) String variables with a width of 8 characters or
 fewer are called @dfn{short string variables}.  Short string variables

-can be used in many procedures where @dfn{long string variables} (those
+may be used in a few contexts where @dfn{long string variables} (those

 with widths greater than 8) are not allowed.
 
 with widths greater than 8) are not allowed.
 

-Certain systems may consider strings longer than 8
-characters to be short strings.  Eight characters represents a minimum
-figure for the maximum length of a short string.
-

 @item Position
 Variables in the dictionary are arranged in a specific order.
 @cmd{DISPLAY} can be used to show this order: see @ref{DISPLAY}.
 @item Position
 Variables in the dictionary are arranged in a specific order.
 @cmd{DISPLAY} can be used to show this order: see @ref{DISPLAY}.


@@ -476,9 +489,14 @@ they are displayed.  Example: a width of 8, with 2 decimal places.
 @item Write format
 Similar to print format, but used by the @cmd{WRITE} command
 (@pxref{WRITE}).
 @item Write format
 Similar to print format, but used by the @cmd{WRITE} command
 (@pxref{WRITE}).

+
+@cindex custom attributes
+@item Custom attributes
+User-defined associations between names and values.  @xref{VARIABLE
+ATTRIBUTE}.

 @end table
 
 @end table
 

-@node System Variables, Sets of Variables, Attributes, Variables
+@node System Variables

 @subsection Variables Automatically Defined by PSPP
 @cindex system variables
 @cindex variables, system
 @subsection Variables Automatically Defined by PSPP
 @cindex system variables
 @cindex variables, system


@@ -522,7 +540,7 @@ was read, in format F20.
 Page width, in characters, in format F3.
 @end table
 
 Page width, in characters, in format F3.
 @end table
 

-@node Sets of Variables, Input and Output Formats, System Variables, Variables
+@node Sets of Variables

 @subsection Lists of variable names
 @cindex @code{TO} convention
 @cindex convention, @code{TO}
 @subsection Lists of variable names
 @cindex @code{TO} convention
 @cindex convention, @code{TO}


@@ -551,7 +569,7 @@ After a set of variables has been defined with @cmd{DATA LIST} or
 another command with this method, the same set can be referenced on
 later commands using the same syntax.
 
 another command with this method, the same set can be referenced on
 later commands using the same syntax.
 

-@node Input and Output Formats, Scratch Variables, Sets of Variables, Variables
+@node Input and Output Formats

 @subsection Input and Output Formats
 
 @cindex formats
 @subsection Input and Output Formats
 
 @cindex formats


@@ -1146,6 +1164,7 @@ trailing white space.
 The maximum width for time and date formats is 40 columns.  Minimum
 input and output width for each of the time and date formats is shown
 below:
 The maximum width for time and date formats is 40 columns.  Minimum
 input and output width for each of the time and date formats is shown
 below:

+

 @float
 @multitable {DATETIME} {Min. Input Width} {Min. Output Width} {4-digit year}
 @headitem Format @tab Min. Input Width @tab Min. Output Width @tab Option 
 @float
 @multitable {DATETIME} {Min. Input Width} {Min. Output Width} {4-digit year}
 @headitem Format @tab Min. Input Width @tab Min. Output Width @tab Option 


@@ -1232,7 +1251,7 @@ as hex digit pairs.  On output, hex digits are output in uppercase; on
 input, uppercase and lowercase are both accepted.  The default output
 format is A format with half the input width.
 
 input, uppercase and lowercase are both accepted.  The default output
 format is A format with half the input width.
 

-@node Scratch Variables,  , Input and Output Formats, Variables
+@node Scratch Variables

 @subsection Scratch Variables
 
 @cindex scratch variables
 @subsection Scratch Variables
 
 @cindex scratch variables


@@ -1331,6 +1350,14 @@ file, or scratch file.  Most often, a file handle is specified as the
 name of a file as a string, that is, enclosed within @samp{'} or
 @samp{"}.
 
 name of a file as a string, that is, enclosed within @samp{'} or
 @samp{"}.
 

+A file name string that begins or ends with @samp{|} is treated as the
+name of a command to pipe data to or from.  You can use this feature
+to read data over the network using a program such as @samp{curl}
+(e.g.@: @code{GET '|curl -s -S http://example.com/mydata.sav'}), to
+read compressed data from a file using a program such as @samp{zcat}
+(e.g.@: @code{GET '|zcat mydata.sav.gz'}), and for many other
+purposes.
+

 PSPP also supports declaring named file handles with the @cmd{FILE
 HANDLE} command.  This command associates an identifier of your choice
 (the file handle's name) with a file.  Later, the file handle name can
 PSPP also supports declaring named file handles with the @cmd{FILE
 HANDLE} command.  This command associates an identifier of your choice
 (the file handle's name) with a file.  Later, the file handle name can


@@ -1459,4 +1486,3 @@ The first nonterminal defined in a set of productions is called the
 @dfn{start symbol}.  The start symbol defines the entire syntax for
 that command.
 @end itemize
 @dfn{start symbol}.  The start symbol defines the entire syntax for
 that command.
 @end itemize

-@setfilename ignored