Implemented the INSERT command.

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

diff --git a/doc/q2c.texi b/doc/q2c.texi
index 0e25019b468e6b796a1517a605c5b8c55ef8c81a..fb61173e9b9ee592a26e58342d530cf254f382c1 100644 (file)
--- a/doc/q2c.texi
+++ b/doc/q2c.texi
@@ -1,4 +1,4 @@
-@node q2c Input Format, , Data File Format, Top
+@node q2c Input Format
 @appendix @code{q2c} Input Format
 
 PSPP statistical procedures have a bizarre and somewhat irregular
@@ -13,7 +13,7 @@ hooks for the exceptional cases.  This parser generator is named
 * Grammar Rules::               Syntax of the grammar rules.
 @end menu
 
-@node Invoking q2c, q2c Input Structure, q2c Input Format, q2c Input Format
+@node Invoking q2c
 @section Invoking q2c
 
 @example
@@ -25,7 +25,7 @@ exactly two command-line arguments, which are the input file name and
 output file name, respectively.  @code{q2c} does not accept any
 command-line options.
 
-@node q2c Input Structure, Grammar Rules, Invoking q2c, q2c Input Format
+@node q2c Input Structure
 @section @code{q2c} Input Structure
 
 @code{q2c} input files are divided into two sections: the grammar rules
@@ -78,7 +78,7 @@ declared by the parser.  Only needs to be invoked if subcommands of type
 @code{string} are used in the grammar rules.
 @end table
 
-@node Grammar Rules,  , q2c Input Structure, q2c Input Format
+@node Grammar Rules
 @section Grammar Rules
 
 The grammar rules describe the format of the syntax that the parser
@@ -104,7 +104,7 @@ backslash within a string.
 
 @item Special character
 
-Other characters, other than whitespace, constitute tokens in
+Other characters, other than white space, constitute tokens in
 themselves.
 
 @end table
@@ -112,41 +112,46 @@ themselves.
 The syntax of the grammar rules is as follows:
 
 @example
-grammar-rules ::= ID : subcommands .
+grammar-rules ::= command-name opt-prefix : subcommands .
+command-name ::= ID
+             ::= STRING
+opt-prefix ::=
+           ::= ( ID )
 subcommands ::= subcommand
             ::= subcommands ; subcommand
 @end example
 
-The syntax begins with an ID or STRING token that gives the name of the
-procedure to be parsed.  The rest of the syntax consists of subcommands
-separated by semicolons (@samp{;}) and terminated with a full stop
-(@samp{.}).
+The syntax begins with an ID token that gives the name of the
+procedure to be parsed.  For command names that contain multiple
+words, a STRING token may be used instead, e.g.@: @samp{"FILE
+HANDLE"}.  Optionally, an ID in parentheses specifies a prefix used
+for all file-scope identifiers declared by the emitted code.
+
+The rest of the syntax consists of subcommands separated by semicolons
+(@samp{;}) and terminated with a full stop (@samp{.}).
 
 @example
-subcommand ::= sbc-options ID sbc-defn
-sbc-options ::= 
-            ::= sbc-option
-            ::= sbc-options sbc-options
-sbc-option ::= *
-           ::= +
-           ::= ^
+subcommand ::= default-opt arity-opt ID sbc-defn
+default-opt ::=
+            ::= *
+arity-opt ::=
+          ::= +
+          ::= ^
 sbc-defn ::= opt-prefix = specifiers
          ::= [ ID ] = array-sbc
          ::= opt-prefix = sbc-special-form
-opt-prefix ::=
-           ::= ( ID )
 @end example
 
-Each subcommand can be prefixed with one or more option characters.  An
-asterisk (@samp{*}) is used to indicate the default subcommand; the
-keyword used for the default subcommand can be omitted in the PSPP
-syntax file.  A plus sign (@samp{+}) is used to indicate that a
-subcommand can appear more than once; if it is not present then that
-subcommand can appear no more than once.
-A carat sign (@samp{^}) is used to indicate that a subcommand must appear
-at least once.
+A subcommand that begins with an asterisk (@samp{*}) is the default
+subcommand.  The keyword used for the default subcommand can be omitted
+in the PSPP syntax file.
+
+A plus sign (@samp{+}) indicates that a subcommand can appear more than
+once.  A caret (@samp{^}) indicate that a subcommand must appear exactly
+once.  A subcommand marked with neither character may appear once or not
+at all, but not more than once.
 
-The subcommand name appears after the option characters.
+The subcommand name appears after the leading option characters.
 
 There are three forms of subcommands.  The first and most common form
 simply gives an equals sign (@samp{=}) and a list of specifiers, which
@@ -212,14 +217,16 @@ setting-value-options ::=
                       ::= *
 setting-value-type ::= N
                    ::= D
+                   ::= S
 setting-value-restriction ::= 
                           ::= , STRING
 @end example
 
 Settings may have values.  If the value must be enclosed in parentheses,
 then enclose the value declaration in parentheses.  Declare the setting
-type as @samp{n} or @samp{d} for integer or floating point type,
-respectively.  The given @code{ID} is used to construct a variable name.
+type as @samp{n}, @samp{d}, or @samp{s} for integer, floating-point,
+or string type, respectively.  The given @code{ID} is used to
+construct a variable name.
 If option @samp{*} is given, then the value is optional; otherwise it
 must be specified whenever the corresponding setting is specified.  A
 ``restriction'' can also be specified which is a string giving a C