X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Fvariables.texi;h=c1b18edfa600c68923374bc2dd39ac2a76beaf9b;hb=f821734badec2dcca4bdcd2069d22d60dc074c94;hp=c2952fbd531d59fd8ad3ab03701580aa687c191b;hpb=b09b3485e28fba1b07980fd5a5eb6466486b5c07;p=pspp

diff --git a/doc/variables.texi b/doc/variables.texi
index c2952fbd53..c1b18edfa6 100644
--- a/doc/variables.texi
+++ b/doc/variables.texi
@@ -1,75 +1,72 @@
-@node Variable Attributes, Data Manipulation, System and Portable Files, Top
-@chapter Manipulating variables
-
-The variables in the active file dictionary are important.  There are
-several utility functions for examining and adjusting them.
+@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 Manipulating Variables
+@chapter Manipulating Variables
+@cindex Variables
+
+Every value in a dataset is associated with a @dfn{variable}.
+Variables describe what the values represent and properties of those values,
+such as the format in which they should be displayed, whether they are numeric
+or alphabetic and how missing values should be represented.
+There are several utility commands for examining and adjusting variables.
 
 @menu
-* ADD VALUE LABELS::            Add value labels to variables.
-* DELETE VARIABLES::            Delete variables.
-* DISPLAY::                     Display variable names & descriptions.
-* DISPLAY VECTORS::             Display a list of vectors.
-* FORMATS::                     Set print and write formats.
-* LEAVE::                       Don't clear variables between cases.
-* MISSING VALUES::              Set missing values for variables.
-* MODIFY VARS::                 Rename, reorder, and drop variables.
+* DISPLAY::                     Display information about the active dataset.
 * NUMERIC::                     Create new numeric variables.
-* PRINT FORMATS::               Set variable print formats.
-* RENAME VARIABLES::            Rename variables.
-* VALUE LABELS::                Set value labels for variables.
 * STRING::                      Create new string variables.
+* RENAME VARIABLES::            Rename variables.
+* SORT VARIABLES::              Reorder variables.
+* DELETE VARIABLES::            Delete variables.
 * VARIABLE LABELS::             Set variable labels for variables.
+* PRINT FORMATS::               Set variable print formats.
+* WRITE FORMATS::               Set variable write formats.
+* FORMATS::                     Set print and write formats.
+* VALUE LABELS::                Set value labels for variables.
+* ADD VALUE LABELS::            Add value labels to variables.
+* MISSING VALUES::              Set missing values for variables.
+* VARIABLE ATTRIBUTE::          Set custom attributes on variables.
 * VARIABLE ALIGNMENT::          Set the alignment for display.
 * VARIABLE WIDTH::              Set the display width.
 * VARIABLE LEVEL::              Set the measurement level.
+* VARIABLE ROLE::               Set the role that a variable fills in analysis.
 * VECTOR::                      Declare an array of variables.
-* WRITE FORMATS::               Set variable write formats.
+* MRSETS::                      Add, modify, and list multiple response sets.
+* LEAVE::                       Don't clear variables between cases.
 @end menu
 
-@node ADD VALUE LABELS, DELETE VARIABLES, Variable Attributes, Variable Attributes
-@section ADD VALUE LABELS
-@vindex ADD VALUE LABELS
-
-@display 
-ADD VALUE LABELS
-        /var_list value 'label' [value 'label']@dots{}
-@end display
-
-@cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
-LABELS} (@pxref{VALUE LABELS}), but it does not clear value
-labels from the variables before adding the ones specified.
-
-@node DELETE VARIABLES, DISPLAY, ADD VALUE LABELS, Variable Attributes
-@section DELETE VARIABLES
-@vindex DELETE VARIABLES
-
-@display
-DELETE VARIABLES var_list.
-@end display
-
-@cmd{DELETE VARIABLES} deletes the specified variables from the
-dictionary.  It may not be used to delete all variables from the
-dictionary; use @cmd{NEW FILE} to do that (@pxref{NEW FILE}).
-
-@cmd{DELETE VARIABLES} should not used after defining transformations
-and before executing a procedure.  If it is used in such a context, it
-causes the data to be read.  If it is used while @cmd{TEMPORARY} is in
-effect, it causes the temporary transformations to become permanent.
-
-@node DISPLAY, DISPLAY VECTORS, DELETE VARIABLES, Variable Attributes
+@node DISPLAY
 @section DISPLAY
 @vindex DISPLAY
 
+The @cmd{DISPLAY} command displays information about the variables in the active dataset.
+A variety of different forms of information can be requested.
+By default, all variables in the active dataset are displayed.  However you can select
+variables of interest using the @subcmd{/VARIABLES} subcommand.
+
 @display
-DISPLAY @{NAMES,INDEX,LABELS,VARIABLES,DICTIONARY,SCRATCH@}
-        [SORTED] [var_list]
+DISPLAY [SORTED] NAMES [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] INDEX [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] LABELS [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] VARIABLES [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] DICTIONARY [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] SCRATCH [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] ATTRIBUTES [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] @@ATTRIBUTES [[/VARIABLES=]@var{var_list}].
+DISPLAY [SORTED] VECTORS.
 @end display
 
-@cmd{DISPLAY} displays requested information on variables.  Variables can
-optionally be sorted alphabetically.  The entire dictionary or just
-specified variables can be described.
-
-One of the following keywords can be present:
+The following keywords primarily cause information about variables to
+be displayed.  With these keywords, by default information is
+displayed about all variable in the active dataset, in the order that
+variables occur in the active dataset dictionary.  The @subcmd{SORTED} keyword
+causes output to be sorted alphabetically by variable name.
 
 @table @asis
 @item NAMES
@@ -77,7 +74,7 @@ The variables' names are displayed.
 
 @item INDEX
 The variables' names are displayed along with a value describing their
-position within the active file dictionary.
+position within the active dataset dictionary.
 
 @item LABELS
 Variable names, positions, and variable labels are displayed.
@@ -91,381 +88,536 @@ Variable names, positions, print and write formats, missing values,
 variable labels, and value labels are displayed.
 
 @item SCRATCH
-Varible names are displayed, for scratch variables only (@pxref{Scratch
+Variable names are displayed, for scratch variables only (@pxref{Scratch
 Variables}).
-@end table
 
-If SORTED is specified, then the variables are displayed in ascending
-order based on their names; otherwise, they are displayed in the order
-that they occur in the active file dictionary.
+@item ATTRIBUTES
+@itemx @@ATTRIBUTES
+Datafile and variable attributes are displayed.
+The first form of the command omits those attributes
+whose names begin with @code{@@} or @code{$@@}.
+In the second for, all datafile and variable attributes are displayed.
+@end table
 
-@node DISPLAY VECTORS, FORMATS, DISPLAY, Variable Attributes
-@section DISPLAY VECTORS
-@vindex DISPLAY VECTORS
+With the @code{VECTOR} keyword, @cmd{DISPLAY} lists all the currently
+declared vectors.  If the @subcmd{SORTED} keyword is given, the vectors are
+listed in alphabetical order; otherwise, they are listed in textual
+order of definition within the @pspp{} syntax file.
 
-@display
-DISPLAY VECTORS.
-@end display
+For related commands, see @ref{DISPLAY DOCUMENTS} and @ref{DISPLAY
+FILE LABEL}.
 
-@cmd{DISPLAY VECTORS} lists all the currently declared vectors.
+@node NUMERIC
+@section NUMERIC
+@vindex NUMERIC
 
-@node FORMATS, LEAVE, DISPLAY VECTORS, Variable Attributes
-@section FORMATS
-@vindex FORMATS
+@cmd{NUMERIC} explicitly declares new numeric variables, optionally
+setting their output formats.
 
 @display
-FORMATS var_list (fmt_spec).
+NUMERIC @var{var_list} [(@var{fmt_spec})] [/@var{var_list} [(@var{fmt_spec})]]@dots{}
 @end display
 
-@cmd{FORMATS} set both print and write formats for the specified
-numeric variables to the specified format specification.
-@xref{Input and Output Formats}.
-
-Specify a list of variables followed by a format specification in
-parentheses.  The print and write formats of the specified variables
-will be changed.
+Specify the names of the new numeric variables as @var{var_list}.  If
+you wish to set the variables' output formats, follow their names by
+an output format specification in parentheses (@pxref{Input and Output
+Formats}); otherwise, the default is F8.2.
 
-Additional lists of variables and formats may be included if they are
-delimited by a slash (@samp{/}).
+Variables created with @cmd{NUMERIC} are initialized to the
+system-missing value.
 
-@cmd{FORMATS} takes effect immediately.  It is not affected by
-conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
+@node STRING
+@section STRING
+@vindex STRING
 
-@node LEAVE, MISSING VALUES, FORMATS, Variable Attributes
-@section LEAVE
-@vindex LEAVE
+@cmd{STRING} creates new string variables.
 
 @display
-LEAVE var_list.
+STRING @var{var_list} (@var{fmt_spec}) [/@var{var_list} (@var{fmt_spec})] [@dots{}].
 @end display
 
-@cmd{LEAVE} prevents the specified variables from being
-reinitialized whenever a new case is processed.
+Specify a list of names for the variable you want to create,
+followed by the desired output format specification in
+parentheses (@pxref{Input and Output Formats}).
+Variable widths are
+implicitly derived from the specified output formats.
+The created variables will be initialized to spaces.
 
-Normally, when a data file is processed, every variable in the active
-file is initialized to the system-missing value or spaces at the
-beginning of processing for each case.  When a variable has been
-specified on @cmd{LEAVE}, this is not the case.  Instead, that variable is
-initialized to 0 (not system-missing) or spaces for the first case.
-After that, it retains its value between cases.
+If you want to create several variables with  distinct
+output formats, you can either use two or more separate @cmd{STRING} commands,
+or you can specify further variable list and format specification pairs, each separated
+from the previous by a slash (@samp{/}).
 
-This becomes useful for counters.  For instance, in the example below
-the variable SUM maintains a running total of the values in the ITEM
-variable.
+The following example is one way to create three string variables; Two of the
+variables have format A24 and the other A80:
+@example
+STRING firstname lastname (A24) / address (A80).
+@end example
 
+@noindent Here is another way to achieve the same result:
 @example
-DATA LIST /ITEM 1-3.
-COMPUTE SUM=SUM+ITEM.
-PRINT /ITEM SUM.
-LEAVE SUM
-BEGIN DATA.
-123
-404
-555
-999
-END DATA.
+STRING firstname lastname (A24).
+STRING address (A80).
 @end example
 
-@noindent Partial output from this example:
+@noindent @dots{} and here is yet another way:
 
 @example
-123   123.00
-404   527.00
-555  1082.00
-999  2081.00
+STRING firstname (A24).
+STRING lastname (A24).
+STRING address (A80).
 @end example
 
-It is best to use @cmd{LEAVE} command immediately before invoking a
-procedure command, because the left status of variables is reset by
-certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
-Left status is also reset by all procedure invocations.
+@node RENAME VARIABLES
+@section RENAME VARIABLES
+@vindex RENAME VARIABLES
 
-@node MISSING VALUES, MODIFY VARS, LEAVE, Variable Attributes
-@section MISSING VALUES
-@vindex MISSING VALUES
+@cmd{RENAME VARIABLES} changes the names of variables in the active
+dataset.
 
 @display
-MISSING VALUES var_list (missing_values).
-
-missing_values takes one of the following forms:
-        num1
-        num1, num2
-        num1, num2, num3
-        num1 THRU num2
-        num1 THRU num2, num3
-        string1
-        string1, string2
-        string1, string2, string3
-As part of a range, LO or LOWEST may take the place of num1;
-HI or HIGHEST may take the place of num2.
+RENAME VARIABLES (@var{old_names}=@var{new_names})@dots{} .
 @end display
 
-@cmd{MISSING VALUES} sets user-missing values for numeric and
-short string variables.  Long string variables may not have missing
-values.
+Specify lists of the old variable names and new
+variable names, separated by an equals sign (@samp{=}), within
+parentheses.  There must be the same number of old and new variable
+names.  Each old variable is renamed to the corresponding new variable
+name.  Multiple parenthesized groups of variables may be specified.
+When the old and new variable names contain only a single variable name,
+the parentheses are optional.
 
-Specify a list of variables, followed by a list of their user-missing
-values in parentheses.  Up to three discrete values may be given, or,
-for numeric variables only, a range of values optionally accompanied by
-a single discrete value.  Ranges may be open-ended on one end, indicated
-through the use of the keyword LO or LOWEST or HI or HIGHEST.
+@cmd{RENAME VARIABLES} takes effect immediately.  It does not cause the data
+to be read.
 
-The @cmd{MISSING VALUES} command takes effect immediately.  It is not
-affected by conditional and looping constructs such as @cmd{DO IF} or
-@cmd{LOOP}.
+@cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
+(@pxref{TEMPORARY}).
+
+@node SORT VARIABLES
+@section SORT VARIABLES
+@vindex SORT VARIABLES
 
-@node MODIFY VARS, NUMERIC, MISSING VALUES, Variable Attributes
-@section MODIFY VARS
-@vindex MODIFY VARS
+@cmd{SORT VARIABLES} reorders the variables in the active dataset's dictionary
+according to a chosen sort key.
 
-@display 
-MODIFY VARS
-        /REORDER=@{FORWARD,BACKWARD@} @{POSITIONAL,ALPHA@} (var_list)@dots{}
-        /RENAME=(old_names=new_names)@dots{}
-        /@{DROP,KEEP@}=var_list
-        /MAP    
+@display
+SORT VARIABLES [BY]
+    (NAME | TYPE | FORMAT | LABEL | VALUES | MISSING | MEASURE
+     | ROLE | COLUMNS | ALIGNMENT | ATTRIBUTE @var{name})
+    [(D)].
 @end display
 
-@cmd{MODIFY VARS} reorders, renames, and deletes variables in the
-active file.
+The main specification is one of the following identifiers, which
+determines how the variables are sorted:
 
-At least one subcommand must be specified, and no subcommand may be
-specified more than once.  DROP and KEEP may not both be specified.
+@table @asis
+@item NAME
+Sorts the variables according to their names, in a case-insensitive
+fashion.  However, when variable names differ only in a number at the
+end, they are sorted numerically.  For example, @code{VAR5} is sorted
+before @code{VAR400} even though @samp{4} precedes @samp{5}.
+
+@item TYPE
+Sorts numeric variables before string variables, and shorter string
+variables before longer ones.
+
+@item FORMAT
+Groups variables by print format; within a format, sorts narrower
+formats before wider ones; with the same format and width, sorts fewer
+decimal places before more decimal places.
+@xref{FORMATS}.
+
+@item LABEL
+Sorts variables without a variable label before those with one.
+@xref{VARIABLE LABELS}.
+
+@item VALUES
+Sorts variables without value labels before those with some.
+@xref{VALUE LABELS}.
+
+@item MISSING
+Sorts variables without missing values before those with some.
+@xref{MISSING VALUES}.
+
+@item MEASURE
+Sorts nominal variables first, followed by ordinal variables, followed
+by scale variables.  @xref{VARIABLE LEVEL}.
+
+@item ROLE
+Groups variables according to their role.  @xref{VARIABLE ROLE}.
+
+@item COLUMNS
+Sorts variables in ascending display width.  @xref{VARIABLE WIDTH}.
+
+@item ALIGNMENT
+Sorts variables according to their alignment, first left-aligned, then
+right-aligned, then centered.  @xref{VARIABLE ALIGNMENT}.
+
+@item ATTRIBUTE @var{name}
+Sorts variables according to the first value of their @var{name}
+attribute.  Variables without attribute are sorted first.
+@xref{VARIABLE ATTRIBUTE}.
+@end table
 
-The REORDER subcommand changes the order of variables in the active
-file.  Specify one or more lists of variable names in parentheses.  By
-default, each list of variables is rearranged into the specified order.
-To put the variables into the reverse of the specified order, put
-keyword BACKWARD before the parentheses.  To put them into alphabetical
-order in the dictionary, specify keyword ALPHA before the parentheses.
-BACKWARD and ALPHA may also be combined.
+Only one sort criterion can be specified.  The sort is ``stable,'' so
+to sort on multiple criteria one may perform multiple sorts.  For
+example, the following will sort primarily based on alignment, with
+variables that have the same alignment ordered based on display width:
 
-To rename variables in the active file, specify RENAME, an equals sign
-(@samp{=}), and lists of the old variable names and new variable names
-separated by another equals sign within parentheses.  There must be the
-same number of old and new variable names.  Each old variable is renamed to
-the corresponding new variable name.  Multiple parenthesized groups of
-variables may be specified.
+@example
+SORT VARIABLES BY COLUMNS.
+SORT VARIABLES BY ALIGNMENT.
+@end example
+
+Specify @code{(D)} to reverse the sort order.
+
+@node DELETE VARIABLES
+@section DELETE VARIABLES
+@vindex DELETE VARIABLES
 
-The DROP subcommand deletes a specified list of variables from the
-active file.
+@cmd{DELETE VARIABLES} deletes the specified variables from the dictionary.
 
-The KEEP subcommand keeps the specified list of variables in the active
-file.  Any unlisted variables are deleted from the active file.
+@display
+DELETE VARIABLES @var{var_list}.
+@end display
 
-MAP is currently ignored.
+@cmd{DELETE VARIABLES} should not be used after defining transformations
+but before executing a procedure.  If it is used in such a context, it
+causes the data to be read.  If it is used while @cmd{TEMPORARY} is in
+effect, it causes the temporary transformations to become permanent.
 
-If either DROP or KEEP is specified, the data is read; otherwise it is
-not.
+@cmd{DELETE VARIABLES} may not be used to delete all variables from the
+dictionary; use @cmd{NEW FILE} to do that (@pxref{NEW FILE}).
 
-@cmd{MODIFY VARS} may not be specified following @cmd{TEMPORARY}
-(@pxref{TEMPORARY}).
+@node VARIABLE LABELS
+@section VARIABLE LABELS
+@vindex VARIABLE LABELS
 
-@node NUMERIC, PRINT FORMATS, MODIFY VARS, Variable Attributes
-@section NUMERIC
-@vindex NUMERIC
+In addition to a variable's name, each variable can have a
+@dfn{label}.  Whereas a variable name is a concise, easy-to-type
+mnemonic for the variable, a label may be longer and more descriptive.
 
 @display
-NUMERIC /var_list [(fmt_spec)].
+VARIABLE LABELS
+        @var{variable} '@var{label}'
+        [@var{variable} '@var{label}']@dots{}
 @end display
 
-@cmd{NUMERIC} explicitly declares new numeric variables, optionally
-setting their output formats.
+@cmd{VARIABLE LABELS} associates explanatory names
+with variables.  This name, called a @dfn{variable label}, is displayed by
+statistical procedures.
 
-Specify a slash (@samp{/}), followed by the names of the new numeric
-variables.  If you wish to set their output formats, follow their names
-by an output format specification in parentheses (@pxref{Input and Output
-Formats}); otherwise, the default is F8.2.
+Specify each variable followed by its label as a quoted string.
+Variable-label pairs may be separated by an optional slash @samp{/}.
 
-Variables created with @cmd{NUMERIC} are initialized to the
-system-missing value.
+If a listed variable already has a label, the new one replaces it.
+Specifying an empty string as the label, e.g.@:@samp{''}, removes a
+label.
 
-@node PRINT FORMATS, RENAME VARIABLES, NUMERIC, Variable Attributes
+@node PRINT FORMATS
 @section PRINT FORMATS
 @vindex PRINT FORMATS
 
 @display
-PRINT FORMATS var_list (fmt_spec).
+PRINT FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
 @end display
 
 @cmd{PRINT FORMATS} sets the print formats for the specified
-numeric variables to the specified format specification.
+variables to the specified format specification.
 
 Its syntax is identical to that of @cmd{FORMATS} (@pxref{FORMATS}),
 but @cmd{PRINT FORMATS} sets only print formats, not write formats.
 
-@node RENAME VARIABLES, VALUE LABELS, PRINT FORMATS, Variable Attributes
-@section RENAME VARIABLES
-@vindex RENAME VARIABLES
+@node WRITE FORMATS
+@section WRITE FORMATS
+@vindex WRITE FORMATS
 
 @display
-RENAME VARIABLES (old_names=new_names)@dots{} .
+WRITE FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
 @end display
 
-@cmd{RENAME VARIABLES} changes the names of variables in the active
-file.  Specify lists of the old variable names and new
-variable names, separated by an equals sign (@samp{=}), within
-parentheses.  There must be the same number of old and new variable
-names.  Each old variable is renamed to the corresponding new variable
-name.  Multiple parenthesized groups of variables may be specified.
+@cmd{WRITE FORMATS} sets the write formats for the specified variables
+to the specified format specification.  Its syntax is identical to
+that of @cmd{FORMATS} (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
+write formats, not print formats.
 
-@cmd{RENAME VARIABLES} takes effect immediately.  It does not cause the data
-to be read.
+@node FORMATS
+@section FORMATS
+@vindex FORMATS
 
-@cmd{RENAME VARIABLES} may not be specified following @cmd{TEMPORARY}
-(@pxref{TEMPORARY}).
+@display
+FORMATS @var{var_list} (@var{fmt_spec}) [@var{var_list} (@var{fmt_spec})]@dots{}.
+@end display
+
+@cmd{FORMATS} set both print and write formats for the specified
+variables to the specified format specification.
+@xref{Input and Output Formats}.
+
+Specify a list of variables followed by a format specification in
+parentheses.  The print and write formats of the specified variables
+will be changed.  All of the variables listed together must have
+the same type and, for string variables, the same width.
+
+Additional lists of variables and formats may be included following
+the first one.
 
-@node VALUE LABELS, STRING, RENAME VARIABLES, Variable Attributes
+@cmd{FORMATS} takes effect immediately.  It is not affected by
+conditional and looping structures such as @cmd{DO IF} or @cmd{LOOP}.
+
+@node VALUE LABELS
 @section VALUE LABELS
 @vindex VALUE LABELS
 
-@display 
+The values of a variable can be associated with an arbitrary text string.
+In this way, a short value can stand for a longer, more descriptive label.
+
+Both numeric and string variables can be given labels.  For string
+variables, the values are case-sensitive, so that, for example, a
+capitalized value and its lowercase variant would have to be labeled
+separately if both are present in the data.
+
+@display
 VALUE LABELS
-        /var_list value 'label' [value 'label']@dots{}
+        /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
 @end display
 
-@cmd{VALUE LABELS} allows values of numeric and short string
-variables to be associated with labels.  In this way, a short value can
-stand for a long value.
+@cmd{VALUE LABELS} allows values of variables to be associated with labels.
 
-To set up value labels for a set of variables, specify the
+To set up value labels for one or more variables, specify the
 variable names after a slash (@samp{/}), followed by a list of values
-and their associated labels, separated by spaces.  Long string
-variables may not be specified.
+and their associated labels, separated by spaces.
+
+Value labels in output are normally broken into lines automatically.
+Put @samp{\n} in a label string to force a line break at that point.
+The label may still be broken into lines at additional points.
 
 Before @cmd{VALUE LABELS} is executed, any existing value labels
 are cleared from the variables specified.  Use @cmd{ADD VALUE LABELS}
 (@pxref{ADD VALUE LABELS}) to add value labels without clearing those
 already present.
 
-@node STRING, VARIABLE LABELS, VALUE LABELS, Variable Attributes
-@section STRING
-@vindex STRING
+@node ADD VALUE LABELS
+@section ADD VALUE LABELS
+@vindex ADD VALUE LABELS
+
+@cmd{ADD VALUE LABELS} has the same syntax and purpose as @cmd{VALUE
+LABELS} (@pxref{VALUE LABELS}), but it does not clear value
+labels from the variables before adding the ones specified.
 
 @display
-STRING /var_list (fmt_spec).
+ADD VALUE LABELS
+        /@var{var_list} @var{value} '@var{label}' [@var{value} '@var{label}']@dots{}
 @end display
 
-@cmd{STRING} creates new string variables for use in
-transformations.
-
-Specify a slash (@samp{/}), followed by the names of the string
-variables to create and the desired output format specification in
-parentheses (@pxref{Input and Output Formats}).  Variable widths are
-implicitly derived from the specified output formats.
 
-Created variables are initialized to spaces.
+@node MISSING VALUES
+@section MISSING VALUES
+@vindex MISSING VALUES
 
+In many situations the data available for analysis is incomplete and a placeholder
+must be used in place of a value to indicate that the value is unknown.  One way
+that missing values are represented is through the $SYSMIS variable
+(@pxref{System Variables}).  Another, more flexible way is through
+@dfn{user-missing values} which are determined on a per variable basis.
 
-@node VARIABLE LABELS, VARIABLE ALIGNMENT, STRING, Variable Attributes
-@section VARIABLE LABELS
-@vindex VARIABLE LABELS
+The @cmd{MISSING VALUES} command sets user-missing values for variables.
 
 @display
-VARIABLE LABELS
-        var_list 'var_label' 
-        [ /var_list 'var_label']
-        .
-        .
-        .
-        [ /var_list 'var_label']
+MISSING VALUES @var{var_list} (@var{missing_values}).
+
+where @var{missing_values} takes one of the following forms:
+        @var{num1}
+        @var{num1}, @var{num2}
+        @var{num1}, @var{num2}, @var{num3}
+        @var{num1} THRU @var{num2}
+        @var{num1} THRU @var{num2}, @var{num3}
+        @var{string1}
+        @var{string1}, @var{string2}
+        @var{string1}, @var{string2}, @var{string3}
+As part of a range, @subcmd{LO} or @subcmd{LOWEST} may take the place of @var{num1};
+@subcmd{HI} or @subcmd{HIGHEST} may take the place of @var{num2}.
 @end display
 
-@cmd{VARIABLE LABELS} associates explanatory names
-with variables.  This name, called a @dfn{variable label}, is displayed by
-statistical procedures.
+@cmd{MISSING VALUES} sets user-missing values for numeric and string
+variables.  Long string variables may have missing values, but
+characters after the first 8 bytes of the missing value must be
+spaces.
+
+Specify a list of variables, followed by a list of their user-missing
+values in parentheses.  Up to three discrete values may be given, or,
+for numeric variables only, a range of values optionally accompanied by
+a single discrete value.  Ranges may be open-ended on one end, indicated
+through the use of the
+keyword @subcmd{LO} or @subcmd{LOWEST} or @subcmd{HI} or @subcmd{HIGHEST}.
+
+The @cmd{MISSING VALUES} command takes effect immediately.  It is not
+affected by conditional and looping constructs such as @cmd{DO IF} or
+@cmd{LOOP}.
+
+@node VARIABLE ATTRIBUTE
+@section VARIABLE ATTRIBUTE
+@vindex VARIABLE ATTRIBUTE
 
-To assign a variable label to a group of variables, specify a 
-list of variable names and the variable label as a string.
-To assign different labels to different variables in the same command, 
-preceed the subsequent variable list with a slash (@samp{/}).
+@cmd{VARIABLE ATTRIBUTE} adds, modifies, or removes user-defined
+attributes associated with variables in the active dataset.  Custom
+variable attributes are not interpreted by @pspp{}, but they are saved as
+part of system files and may be used by other software that reads
+them.
 
+@display
+VARIABLE ATTRIBUTE
+         VARIABLES=@var{var_list}
+         ATTRIBUTE=@var{name}('@var{value}') [@var{name}('@var{value}')]@dots{}
+         ATTRIBUTE=@var{name}@b{[}@var{index}@b{]}('@var{value}') [@var{name}@b{[}@var{index}@b{]}('@var{value}')]@dots{}
+         DELETE=@var{name} [@var{name}]@dots{}
+         DELETE=@var{name}@b{[}@var{index}@b{]} [@var{name}@b{[}@var{index}@b{]}]@dots{}
+@end display
 
-@node VARIABLE ALIGNMENT, VARIABLE WIDTH, VARIABLE LABELS, Variable Attributes
-@comment  node-name,  next,  previous,  u
+The required @subcmd{VARIABLES} subcommand must come first.  Specify the
+variables to which the following @subcmd{ATTRIBUTE} or @subcmd{DELETE} subcommand
+should apply.
+
+Use the @subcmd{ATTRIBUTE} subcommand to add or modify custom variable
+attributes.  Specify the name of the attribute as an identifier
+(@pxref{Tokens}), followed by the desired value, in parentheses, as a
+quoted string.  The specified attributes are then added or modified in
+the variables specified on @subcmd{VARIABLES}.  Attribute names that begin with
+@code{$} are reserved for @pspp{}'s internal use, and attribute names
+that begin with @code{@@} or @code{$@@} are not displayed by most @pspp{}
+commands that display other attributes.  Other attribute names are not
+treated specially.
+
+Attributes may also be organized into arrays.  To assign to an array
+element, add an integer array index enclosed in square brackets
+(@code{[} and @code{]}) between the attribute name and value.  Array
+indexes start at 1, not 0.  An attribute array that has a single
+element (number 1) is not distinguished from a non-array attribute.
+
+Use the @subcmd{DELETE} subcommand to delete an attribute from the variable
+specified on @subcmd{VARIABLES}.  Specify an attribute name by itself to delete
+an entire attribute, including all array elements for attribute
+arrays.  Specify an attribute name followed by an array index in
+square brackets to delete a single element of an attribute array.  In
+the latter case, all the array elements numbered higher than the
+deleted element are shifted down, filling the vacated position.
+
+To associate custom attributes with the entire active dataset, instead of
+with particular variables, use @cmd{DATAFILE ATTRIBUTE} (@pxref{DATAFILE ATTRIBUTE}) instead.
+
+@cmd{VARIABLE ATTRIBUTE} takes effect immediately.  It is not affected
+by conditional and looping structures such as @cmd{DO IF} or
+@cmd{LOOP}.
+
+@node VARIABLE ALIGNMENT
 @section VARIABLE ALIGNMENT
 @vindex VARIABLE ALIGNMENT
 
+@cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing
+purposes.   It  does not affect the display of variables in the @pspp{} output.
+
 @display
 VARIABLE ALIGNMENT
-        var_list ( LEFT | RIGHT | CENTER )
-        [ /var_list ( LEFT | RIGHT | CENTER ) ]
+        @var{var_list} ( LEFT | RIGHT | CENTER )
+        [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
         .
         .
         .
-        [ /var_list ( LEFT | RIGHT | CENTER ) ]
+        [ /@var{var_list} ( LEFT | RIGHT | CENTER ) ]
 @end display
 
-@cmd{VARIABLE ALIGNMENT} sets the alignment of variables for display editing 
-purposes.   This only has effect for third party software.  It does not affect 
-the display of variables in the PSPP output.
-
-
-
-
-@node VARIABLE WIDTH, VARIABLE LEVEL, VARIABLE ALIGNMENT, Variable Attributes
-@comment  node-name,  next,  previous,  up
+@node VARIABLE WIDTH
 @section VARIABLE WIDTH
 @vindex VARIABLE WIDTH
 @display
 VARIABLE WIDTH
-        var_list (width)
-        [ /var_list (width) ] 
+        @var{var_list} (width)
+        [ /@var{var_list} (width) ]
         .
         .
         .
-        [ /var_list (width) ] 
+        [ /@var{var_list} (width) ]
 @end display
 
 @cmd{VARIABLE WIDTH} sets the column width of variables for display editing
-purposes.   This only affects third party software.  It does not affect 
-the display of variables in the PSPP output.
+purposes.   It does not affect the display of variables in the @pspp{} output.
 
 
-@node VARIABLE LEVEL, VECTOR, VARIABLE WIDTH, Variable Attributes
-@comment  node-name,  next,  previous,  up
+@node VARIABLE LEVEL
 @section VARIABLE LEVEL
 @vindex VARIABLE LEVEL
 @display
-VARIABLE LEVEL
-        var_list ( SCALE | NOMINAL | ORDINAL )
-        [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
-        .
-        .
-        .
-        [ /var_list ( SCALE | NOMINAL | ORDINAL ) ]
+@t{VARIABLE LEVEL} @i{variables} @t{(}@{@t{SCALE} @math{|} @t{NOMINAL} @math{|} @t{ORDINAL}@}@t{)}@dots{}
+@end display
+
+@cmd{VARIABLE LEVEL} sets the measurement level of @var{variables} as
+specified.  @xref{Attributes}, for the definitions of the available
+measurement levels.
+
+@node VARIABLE ROLE
+@section VARIABLE ROLE
+@vindex VARIABLE ROLE
+@display
+VARIABLE ROLE
+        /@var{role} @var{var_list}
+        [/@var{role} @var{var_list}]@dots{}
 @end display
 
-@cmd{VARIABLE LEVEL} sets the measurement level of  variables.
-Currently, this has no effect except for certain third party software.
+@cmd{VARIABLE ROLE} sets the intended role of a variable for use in
+dialog boxes in graphical user interfaces.  Each @var{role} specifies
+one of the following roles for the variables that follow it:
+
+@table @code
+@item INPUT
+An input variable, such as an independent variable.
+
+@item TARGET
+An output variable, such as an dependent variable.
+
+@item BOTH
+A variable used for input and output.
+
+@item NONE
+No role assigned.  (This is a variable's default role.)
 
+@item PARTITION
+Used to break the data into groups for testing.
 
-@node VECTOR, WRITE FORMATS, VARIABLE LEVEL, Variable Attributes
+@item SPLIT
+No meaning except for certain third party software.  (This role's
+meaning is unrelated to @cmd{SPLIT FILE}.)
+@end table
+
+The PSPPIRE GUI does not yet use variable roles as intended.
+
+@node VECTOR
 @section VECTOR
 @vindex VECTOR
 
 @display
 Two possible syntaxes:
-        VECTOR vec_name=var_list.
-        VECTOR vec_name_list(count).
+        VECTOR @var{vec_name}=@var{var_list}.
+        VECTOR @var{vec_name_list}(@var{count} [@var{format}]).
 @end display
 
 @cmd{VECTOR} allows a group of variables to be accessed as if they
 were consecutive members of an array with a vector(index) notation.
 
-To make a vector out of a set of existing variables, specify a name for
-the vector followed by an equals sign (@samp{=}) and the variables that
-belong in the vector.
+To make a vector out of a set of existing variables, specify a name
+for the vector followed by an equals sign (@samp{=}) and the variables
+to put in the vector.  The variables must be all numeric or all
+string, and string variables must have the same width.
 
 To make a vector and create variables at the same time, specify one or
-more vector names followed by a count in parentheses.  This will cause
-variables named @code{@var{vec}1} through @code{@var{vec}@var{count}}
-to be created as numeric variables with print and write format F8.2.
-Variable names including numeric suffixes may not exceed 64 characters
-in length, and none of the variables may exist prior to @cmd{VECTOR}.
-
-All the variables in a vector must be the same type.  String variables
-in a vector must all have the same width.
+more vector names followed by a count in parentheses.  This will
+create variables named @code{@var{vec}1} through
+@code{@var{vec}@var{count}}.  By default, the new variables are
+numeric with format F8.2, but an alternate format may be specified
+inside the parentheses before or after the count and separated from it
+by white space or a comma.  With a string format such as A8, the
+variables will be string variables; with a numeric format, they will
+be numeric.  Variable names including the suffixes may not exceed 64
+characters in length, and none of the variables may exist prior to
+@cmd{VECTOR}.
 
 Vectors created with @cmd{VECTOR} disappear after any procedure or
 procedure-like command is executed.  The variables contained in the
@@ -475,20 +627,162 @@ Variables}).
 Variables within a vector may be referenced in expressions using
 @code{vector(index)} syntax.
 
+@node MRSETS
+@section MRSETS
+@vindex MRSETS
 
+@cmd{MRSETS} creates, modifies, deletes, and displays multiple
+response sets.  A multiple response set is a set of variables that
+represent multiple responses to a survey question.
 
+Multiple responses are represented in one of the two following ways:
 
-@node WRITE FORMATS,  , VECTOR, Variable Attributes
-@section WRITE FORMATS
-@vindex WRITE FORMATS
+@itemize @bullet
+@item
+A @dfn{multiple dichotomy set} is analogous to a survey question with
+a set of checkboxes.  Each variable in the set is treated in a Boolean
+fashion: one value (the "counted value") means that the box was
+checked, and any other value means that it was not.
+
+@item
+A @dfn{multiple category set} represents a survey question where the
+respondent is instructed to list up to @var{n} choices.  Each variable
+represents one of the responses.
+@end itemize
 
 @display
-WRITE FORMATS var_list (fmt_spec).
+MRSETS
+    /MDGROUP NAME=@var{name} VARIABLES=@var{var_list} VALUE=@var{value}
+     [CATEGORYLABELS=@{VARLABELS,COUNTEDVALUES@}]
+     [@{LABEL='@var{label}',LABELSOURCE=VARLABEL@}]
+
+    /MCGROUP NAME=@var{name} VARIABLES=@var{var_list} [LABEL='@var{label}']
+
+    /DELETE NAME=@{[@var{names}],ALL@}
+
+    /DISPLAY NAME=@{[@var{names}],ALL@}
 @end display
 
-@cmd{WRITE FORMATS} sets the write formats for the specified numeric
-variables
-to the specified format specification.  Its syntax is identical to
-that of FORMATS (@pxref{FORMATS}), but @cmd{WRITE FORMATS} sets only
-write formats, not print formats.
-@setfilename ignored
+
+Any number of subcommands may be specified in any order.
+
+The @subcmd{MDGROUP} subcommand creates a new multiple dichotomy set or
+replaces an existing multiple response set.  The @subcmd{NAME},
+@subcmd{VARIABLES}, and
+@subcmd{VALUE} specifications are required.  The others are optional:
+
+@itemize @bullet
+@item
+@var{NAME} specifies the name used in syntax for the new multiple dichotomy
+set.  The name must begin with @samp{$}; it must otherwise follow the
+rules for identifiers (@pxref{Tokens}).
+
+@item
+@subcmd{VARIABLES} specifies the variables that belong to the set.  At least
+two variables must be specified.  The variables must be all string or
+all numeric.
+
+@item
+@subcmd{VALUE} specifies the counted value.  If the variables are numeric, the
+value must be an integer.  If the variables are strings, then the
+value must be a string that is no longer than the shortest of the
+variables in the set (ignoring trailing spaces).
+
+@item
+@subcmd{CATEGORYLABELS} optionally specifies the source of the labels for each
+category in the set:
+
+@itemize @minus
+@item
+@subcmd{VARLABELS}, the default, uses variable labels or, for variables without
+variable labels, variable names.  @pspp{} warns if two variables have the
+same variable label, since these categories cannot be distinguished in
+output.
+
+@item
+@subcmd{COUNTEDVALUES} instead uses each variable's value label for the counted
+value.  @pspp{} warns if two variables have the same value label for the
+counted value or if one of the variables lacks a value label, since
+such categories cannot be distinguished in output.
+@end itemize
+
+@item
+@subcmd{LABEL} optionally specifies a label for the multiple response set.  If
+neither @subcmd{LABEL} nor @subcmd{LABELSOURCE=VARLABEL} is specified, the set is
+unlabeled.
+
+@item
+@subcmd{LABELSOURCE=VARLABEL} draws the multiple response set's label from the
+first variable label among the variables in the set; if none of the
+variables has a label, the name of the first variable is used.
+@subcmd{LABELSOURCE=VARLABEL} must be used with @subcmd{CATEGORYLABELS=COUNTEDVALUES}.
+It is mutually exclusive with @subcmd{LABEL}.
+@end itemize
+
+The @subcmd{MCGROUP} subcommand creates a new multiple category set or
+replaces an existing multiple response set.  The @subcmd{NAME} and @subcmd{VARIABLES}
+specifications are required, and @subcmd{LABEL} is optional.  Their meanings
+are as described above in @subcmd{MDGROUP}.  @pspp{} warns if two variables in the
+set have different value labels for a single value, since each of the
+variables in the set should have the same possible categories.
+
+The @subcmd{DELETE} subcommand deletes multiple response groups.  A list of
+groups may be named within a set of required square brackets, or ALL
+may be used to delete all groups.
+
+The @subcmd{DISPLAY} subcommand displays information about defined multiple
+response sets.  Its syntax is the same as the @subcmd{DELETE} subcommand.
+
+Multiple response sets are saved to and read from system files by,
+@i{e.g.}, the @cmd{SAVE} and @cmd{GET} command.  Otherwise, multiple
+response sets are currently used only by third party software.
+
+@node LEAVE
+@section LEAVE
+@vindex LEAVE
+
+@cmd{LEAVE} prevents the specified variables from being
+reinitialized whenever a new case is processed.
+
+@display
+LEAVE @var{var_list}.
+@end display
+
+Normally, when a data file is processed, every variable in the active
+dataset is initialized to the system-missing value or spaces at the
+beginning of processing for each case.  When a variable has been
+specified on @cmd{LEAVE}, this is not the case.  Instead, that variable is
+initialized to 0 (not system-missing) or spaces for the first case.
+After that, it retains its value between cases.
+
+This becomes useful for counters.  For instance, in the example below
+the variable @code{SUM} maintains a running total of the values in the @code{ITEM}
+variable.
+
+@example
+DATA LIST /ITEM 1-3.
+COMPUTE SUM=SUM+ITEM.
+PRINT /ITEM SUM.
+LEAVE SUM
+BEGIN DATA.
+123
+404
+555
+999
+END DATA.
+@end example
+
+@noindent Partial output from this example:
+
+@example
+123   123.00
+404   527.00
+555  1082.00
+999  2081.00
+@end example
+
+It is best to use @cmd{LEAVE} command immediately before invoking a
+procedure command, because the left status of variables is reset by
+certain transformations---for instance, @cmd{COMPUTE} and @cmd{IF}.
+Left status is also reset by all procedure invocations.
+