If multiple elements of the list cover a given category, the last one
in the list takes precedence.
-@c TODO example
+The following example syntax and output show how an explicit category
+can limit the displayed categories:
+
+@example
+CTABLES /TABLE qn1.
+CTABLES /TABLE qn1 /CATEGORIES VARIABLES=qn1 [1, 2, 3].
+@end example
+@psppoutput {ctables27}
@node CTABLES Implicit Categories
@subsubsection Implicit Categories
@code{MISSING=EXCLUDE}. Specify @code{MISSING=INCLUDE} to include
user-missing values. The system-missing value is always excluded.
-@c TODO example
+The following example syntax and output show how
+@code{MISSING=INCLUDE} causes missing values to be included in a
+category list.
+
+@example
+CTABLES /TABLE qn1.
+CTABLES /TABLE qn1 /CATEGORIES VARIABLES=qn1 MISSING=INCLUDE.
+@end example
+@psppoutput {ctables28}
@node CTABLES Totals and Subtotals
@subsubsection Totals and Subtotals
@code{SUBTOTAL="@i{label}"} or @code{HSUBTOTAL="@i{label}"} to specify
a custom label.
-@c TODO
+The following example syntax and output show how to use
+@code{TOTAL=YES} and @code{SUBTOTAL}:
+
+@example
+CTABLES
+ /TABLE qn1
+ /CATEGORIES VARIABLES=qn1 [OTHERNM, SUBTOTAL='Valid Total',
+ MISSING, SUBTOTAL='Missing Total']
+ TOTAL=YES LABEL='Overall Total'.
+@end example
+@psppoutput {ctables29}
By default, or with @code{POSITION=AFTER}, totals are displayed in the
output after the last category and subtotals apply to categories that
precede them. With @code{POSITION=BEFORE}, totals come before the
first category and subtotals apply to categories that follow them.
-@c TODO
-
Only categorical variables may have totals and subtotals. Scalar
variables may be ``totaled'' indirectly by enabling totals and
-subtotals on a categorical variable within which the scalar variable is
-summarized.
+subtotals on a categorical variable within which the scalar variable
+is summarized. For example, the following syntax produces a mean,
+count, and valid count across all data by adding a total on the
+categorical @code{region} variable, as shown:
-@c TODO
+@example
+CTABLES /TABLE=region > qn20 [MEAN, VALIDN]
+ /CATEGORIES VARIABLES=region TOTAL=YES LABEL='All regions'.
+@end example
+@psppoutput {ctables30}
By default, @pspp{} uses the same summary functions for totals and
subtotals as other categories. To summarize totals and subtotals
values with value labels that are covered by ranges or @code{MISSING}
or @code{OTHERNM}.
-@c TODO
+The following example syntax and output show the effect of
+@code{EMPTY=EXCLUDE} for the @code{qns1} variable, in which 0 is labeled
+``None'' but no cases exist with that value:
+
+@example
+CTABLES /TABLE=qns1.
+CTABLES /TABLE=qns1 /CATEGORIES VARIABLES=qns1 EMPTY=EXCLUDE.
+@end example
+@psppoutput {ctables31}
@node CTABLES Titles
@subsection Titles
and measurement level specifications are omitted, and variable labels are used in place of variable names.
@end table
-@c TODO example
-
@node CTABLES Table Formatting
@subsection Table Formatting
Show nothing.
@end table
-@c TODO example
-
@node CTABLES Missing Value Treatment
@subsection Missing Value Treatment
kinds of variables: variables that divide tables into cells (which are
always categorical) and variables being summarized (which may be
categorical or scale). @pspp{} treats missing values differently in
-each kind of variable:
+each kind of variable, as described in the sections below.
+
+@node CTABLES Missing Values for Cell-Defining Variables
+@subsubsection Missing Values for Cell-Defining Variables
-@itemize @bullet
-@item
For variables that divide tables into cells, per-variable category
-options determine which data is analyzed. If any of the categories
-for such a variable would exclude a case, then that case is not
-included.
+options, as described in @ref{CTABLES Per-Variable Category Options},
+determine which data is analyzed. If any of the categories for such a
+variable would exclude a case, then that case is not included.
-@item
-The treatment of missing values in variables being summarized varies
-between scale and scale and categorical variables. The following
-section describes their treatment in detail.
+As an example, consider the following entirely artificial dataset, in
+which @samp{x} and @samp{y} are categorical variables with missing
+value 9, and @samp{z} is scale:
-By default, each summarized variable is considered separately for
-missing value treatment. A section below describes how to consider
-missing values listwise for summarizing scale variables.
-@end itemize
+@psppoutput{ctables32}
-@c TODO example
+Using @samp{x} and @samp{y} to define cells, and summarizing @samp{z},
+by default @pspp{} omits all the cases that have @samp{x} or @samp{y} (or both)
+missing:
+
+@example
+CTABLES /TABLE x > y > z [SUM].
+@end example
+@psppoutput{ctables33}
+
+If, however, we add @code{CATEGORIES} specifications to include
+missing values for @samp{y} or for @samp{x} and @samp{y}, the output
+table includes them, like so:
+
+@example
+CTABLES /TABLE x > y > z [SUM] /CATEGORIES VARIABLES=y MISSING=INCLUDE.
+CTABLES /TABLE x > y > z [SUM] /CATEGORIES VARIABLES=x y MISSING=INCLUDE.
+@end example
+@psppoutput{ctables34}
@node CTABLES Missing Values for Summary Variables
@subsubsection Missing Values for Summary Variables