+@c PSPP - a program for statistical analysis.
+@c Copyright (C) 2017 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 Language
@chapter The @pspp{} language
@cindex language, @pspp{}
referenced. This section describes the details of command ordering,
but most users will have no need to refer to them.
-@pspp{} possesses five internal states, called initial, INPUT PROGRAM,
-FILE TYPE, transformation, and procedure states. (Please note the
+@pspp{} possesses five internal states, called @dfn{initial}, @dfn{input-program}
+@dfn{file-type}, @dfn{transformation}, and @dfn{procedure} states. (Please note the
distinction between the @cmd{INPUT PROGRAM} and @cmd{FILE TYPE}
-@emph{commands} and the INPUT PROGRAM and FILE TYPE @emph{states}.)
+@emph{commands} and the @dfn{input-program} and @dfn{file-type} @emph{states}.)
@pspp{} starts in the initial state. Each successful completion
of a command may cause a state transition. Each type of command has its
@item @cmd{INPUT PROGRAM}
@itemize @bullet
@item
-Invalid in INPUT PROGRAM and FILE TYPE states.
+Invalid in input-program and file-type states.
@item
-Causes a transition to the INPUT PROGRAM state.
+Causes a transition to the intput-program state.
@item
Clears the active dataset.
@end itemize
@item @cmd{FILE TYPE}
@itemize @bullet
@item
-Invalid in INPUT PROGRAM and FILE TYPE states.
+Invalid in intput-program and file-type states.
@item
-Causes a transition to the FILE TYPE state.
+Causes a transition to the file-type state.
@item
Clears the active dataset.
@end itemize
@item Other file definition commands
@itemize @bullet
@item
-Invalid in INPUT PROGRAM and FILE TYPE states.
+Invalid in input-program and file-type states.
@item
Cause a transition to the transformation state.
@item
@item Transformations
@itemize @bullet
@item
-Invalid in initial and FILE TYPE states.
+Invalid in initial and file-type states.
@item
Cause a transition to the transformation state.
@end itemize
@item Restricted transformations
@itemize @bullet
@item
-Invalid in initial, INPUT PROGRAM, and FILE TYPE states.
+Invalid in initial, input-program, and file-type states.
@item
Cause a transition to the transformation state.
@end itemize
@item Procedures
@itemize @bullet
@item
-Invalid in initial, INPUT PROGRAM, and FILE TYPE states.
+Invalid in initial, input-program, and file-type states.
@item
Cause a transition to the procedure state.
@end itemize
@item Custom attributes
User-defined associations between names and values. @xref{VARIABLE
ATTRIBUTE}.
+
+@cindex variable role
+@item Role
+The intended role of a variable for use in dialog boxes in graphical
+user interfaces. @xref{VARIABLE ROLE}.
@end table
@node System Variables
most of the time, the distinction between print and write formats is
unimportant.
-Input and output formats are specified to @pspp{} with a @dfn{format
-specification} of the form @code{TYPEw} or @code{TYPEw.d}, where
-@code{TYPE} is one of the format types described later, @code{w} is a
-field width measured in columns, and @code{d} is an optional number of
-decimal places. If @code{d} is omitted, a value of 0 is assumed. Some
-formats do not allow a nonzero @code{d} to be specified.
+Input and output formats are specified to @pspp{} with
+a @dfn{format specification} of the
+form @subcmd{@var{TYPE}@var{w}} or @code{TYPE@var{w}.@var{d}}, where
+@var{TYPE} is one of the format types described later, @var{w} is a
+field width measured in columns, and @var{d} is an optional number of
+decimal places. If @var{d} is omitted, a value of 0 is assumed. Some
+formats do not allow a nonzero @var{d} to be specified.
The following sections describe the input and output formats supported
by @pspp{}.
In @pspp{}, a @dfn{time} is an interval. The time formats translate
between human-friendly descriptions of time intervals and @pspp{}'s
internal representation of time intervals, which is simply the number of
-seconds in the interval. @pspp{} has two time formats:
+seconds in the interval. @pspp{} has three time formats:
@float
-@multitable {Time Format} {@code{dd-mmm-yyyy HH:MM:SS.ss}} {@code{01-OCT-1978 04:31:17.01}}
+@multitable {Time Format} {@code{dd-mmm-yyyy HH:MM:SS.ss}} {@code{01-OCT-1978 01:31:17.01}}
@headitem Time Format @tab Template @tab Example
-@item TIME @tab @code{hh:MM:SS.ss} @tab @code{04:31:17.01}
+@item MTIME @tab @code{MM:SS.ss} @tab @code{91:17.01}
+@item TIME @tab @code{hh:MM:SS.ss} @tab @code{01:31:17.01}
@item DTIME @tab @code{DD HH:MM:SS.ss} @tab @code{00 04:31:17.01}
@end multitable
@end float
@item MOYR @tab @code{mmm yyyy} @tab @code{OCT 1978}
@item WKYR @tab @code{ww WK yyyy} @tab @code{40 WK 1978}
@item DATETIME @tab @code{dd-mmm-yyyy HH:MM:SS.ss} @tab @code{01-OCT-1978 04:31:17.01}
+@item YMDHMS @tab @code{yyyy-mm-dd HH:MM:SS.ss} @tab @code{1978-01-OCT 04:31:17.01}
@end multitable
@end float
accepted.
@item yyyy
-Year. In output, DATETIME always produces a 4-digit year; other
-formats can produce a 2- or 4-digit year. The century assumed for
-2-digit years depends on the EPOCH setting (@pxref{SET EPOCH}). In
-output, a year outside the epoch causes the whole field to be filled
-with asterisks (@samp{*}).
+Year. In output, DATETIME and YMDHMS always produce 4-digit years;
+other formats can produce a 2- or 4-digit year. The century assumed
+for 2-digit years depends on the EPOCH setting (@pxref{SET EPOCH}).
+In output, a year outside the epoch causes the whole field to be
+filled with asterisks (@samp{*}).
@item jjj
Day of year (Julian day), from 1 to 366. This is exactly three digits
Hour of day, from 0 to 23. Output as exactly two digits.
@item MM
-Minute of hour, from 0 to 59. Output as exactly two digits.
+In MTIME, count of minutes, which may be positive or negative. Output
+as at least two digits.
+
+In other formats, minute of hour, from 0 to 59. Output as exactly two
+digits.
@item SS.ss
Seconds within minute, from 0 to 59. The integer part is output as
@item MOYR @tab 6 @tab 6 @tab 4-digit year
@item WKYR @tab 6 @tab 8 @tab 4-digit year
@item DATETIME @tab 17 @tab 17 @tab seconds
+@item YMDHMS @tab 12 @tab 16 @tab seconds
+@item MTIME @tab 4 @tab 5
@item TIME @tab 5 @tab 5 @tab seconds
@item DTIME @tab 8 @tab 8 @tab seconds
@end multitable
@table @asis
@item 4-digit year
A field 2 columns wider than minimum will include a 4-digit year.
-(DATETIME format always includes a 4-digit year.)
+(DATETIME and YMDHMS formats always include a 4-digit year.)
@item seconds
A field 3 columns wider than minimum will include seconds as well as
When a time or date exceeds the field width, characters are trimmed from
the end until it fits. This can occur in an unusual situation, e.g.@:
with a year greater than 9999 (which adds an extra digit), or for a
-negative value on TIME or DTIME (which adds a leading minus sign).
+negative value on MTIME, TIME, or DTIME (which adds a leading minus sign).
@c What about out-of-range values?