From 919eaaaff409d8c60b762573028677483c9cf932 Mon Sep 17 00:00:00 2001
From: Ben Pfaff <blp@cs.stanford.edu>
Date: Mon, 28 Feb 2022 21:56:32 -0800
Subject: [PATCH] work on docs

---
 doc/language.texi  | 27 ++++++++++++++++++++++++++-
 doc/variables.texi | 13 ++++---------
 2 files changed, 30 insertions(+), 10 deletions(-)

diff --git a/doc/language.texi b/doc/language.texi
index 0bab212897..1c9a4f0105 100644
--- a/doc/language.texi
+++ b/doc/language.texi
@@ -509,7 +509,32 @@ Similar to print format, but used by the @cmd{WRITE} command
 
 @cindex measurement level
 @item Measurement level
-Nominal, ordinal, or scale.
+One of the following:
+
+@table @asis
+@item Nominal
+Each value of a nominal variable represents a distinct category.  The
+possible categories are finite and often have value labels.  The order
+of categories is not significant.  Political parties, US states, and
+yes/no choices are nominal.  Numeric and string variables can be
+nominal.
+
+@item Ordinal
+Ordinal variables also represent distinct categories, but their values
+are arranged according to some natural order.  Likert scales, e.g.@:
+from strongly disagree to strongly agree, are ordinal.  Data grouped
+into ranges, e.g.@: age groups or income groups, are ordinal.  Both
+numeric and string variables can be ordinal.  String values are
+ordered alphabetically, so letter grades from A to F will work as
+expected, but @code{poor}, @code{satisfactory}, @code{excellent} will
+not.
+
+@item Scale
+Scale variables are ones for which differences and ratios are
+meaningful.  These are often values which have a natural unit
+attached, such as age in years, income in dollars, or distance in
+miles.  Only numeric variables are scalar.
+@end table
 
 @cindex custom attributes
 @item Custom attributes
diff --git a/doc/variables.texi b/doc/variables.texi
index 54ae51a687..ab6f83daea 100644
--- a/doc/variables.texi
+++ b/doc/variables.texi
@@ -600,17 +600,12 @@ purposes.   It does not affect the display of variables in the @pspp{} output.
 @section VARIABLE LEVEL
 @vindex VARIABLE LEVEL
 @display
-VARIABLE LEVEL
-        @var{var_list} ( SCALE | NOMINAL | ORDINAL )
-        [ /@var{var_list} ( SCALE | NOMINAL | ORDINAL ) ]
-        .
-        .
-        .
-        [ /@var{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 variables.
-@xref{Attributes}.
+@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
-- 
2.30.2