From 2a5152ef4eea51bdd305543e387b6bbc153dfe5b Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Mon, 27 Sep 2021 23:56:15 -0700 Subject: [PATCH] Work on MATRIX documentation. --- doc/flow-control.texi | 8 ++- doc/matrices.texi | 125 ++++++++++++++++++++++++++++++++++++++++++ doc/pspp.texi | 6 ++ 3 files changed, 137 insertions(+), 2 deletions(-) diff --git a/doc/flow-control.texi b/doc/flow-control.texi index 23539bcfb6..14a4f9b30a 100644 --- a/doc/flow-control.texi +++ b/doc/flow-control.texi @@ -53,20 +53,23 @@ BREAK. @t{!ENDDEFINE.} @end display +@noindent Each @i{argument} takes the following form: @display -@r{@{}@i{!arg_name} @t{=},@t{!POSITIONAL}@r{@}} +@r{@{}@i{!arg_name}@t{=} @math{|} @t{!POSITIONAL}@r{@}} @r{[}@t{!DEFAULT(}@i{default}@t{)}@r{]} @r{[}@t{!NOEXPAND}@r{]} -@r{@{}@t{!TOKENS(}@i{count}@t{)},@t{!CHAREND('}@i{token}@t{')},@t{!ENCLOSE('}@i{start}@t{','}@i{end}@t{')},@t{!CMDEND}@} +@r{@{}@t{!TOKENS(}@i{count}@t{)} @math{|} @t{!CHAREND('}@i{token}@t{')} @math{|} @t{!ENCLOSE('}@i{start}@t{' @math{|} '}@i{end}@t{')} @math{|} @t{!CMDEND}@} @end display +@noindent The following directives may be used within @i{body}: @example !OFFEXPAND !ONEXPAND @end example +@noindent The following functions may be used within the body: @display @t{!BLANKS(}@i{count}@t{)} @@ -83,6 +86,7 @@ The following functions may be used within the body: @t{!UPCASE(}@i{arg}@t{)} @end display +@noindent The body may also include the following constructs: @display @t{!IF (}@i{condition}@t{) !THEN} @i{true-expansion} @t{!ENDIF} diff --git a/doc/matrices.texi b/doc/matrices.texi index 15d1e914c5..cfbf009b67 100644 --- a/doc/matrices.texi +++ b/doc/matrices.texi @@ -576,6 +576,7 @@ END DATA. @node MCONVERT @section MCONVERT +@vindex MCONVERT @display MCONVERT @@ -606,3 +607,127 @@ explicitly request removing the existing data. The @cmd{MCONVERT} command requires its input to be a matrix file. Use @cmd{MATRIX DATA} to convert text input into matrix file format. @xref{MATRIX DATA}, for details. + +@node MATRIX +@section MATRIX +@vindex MATRIX +@vindex END MATRIX + +@subsection Overview + +@display +@t{MATRIX.} +@dots{}@i{matrix commands}@dots{} +@t{END MATRIX.} +@end display + +@noindent +The following basic matrix commands are supported: + +@display +@t{COMPUTE} @i{variable}[(@i{index}[,@i{index}])]=@i{expression}. +@t{CALL} @i{procedure}(@i{argument}, @dots{}). +@t{PRINT} [@i{expression}] + [/@t{FORMAT}=@i{format}] + [/@t{TITLE}=@i{title}] + [/@t{SPACE}=@{@t{NEWPAGE} @math{|} @i{n}@}] + [@{/@t{RLABELS}=@i{string}@dots{} @math{|} /@t{RNAMES}=@i{expression}@}] + [@{/@t{CLABELS}=@i{string}@dots{} @math{|} /@t{CNAMES}=@i{expression}@}]. +@end display + +@noindent +The following matrix commands offer support for flow control: + +@display +@t{DO IF} @i{expression}. + @dots{}@i{matrix commands}@dots{} +[@t{ELSE IF} @i{expression}. + @dots{}@i{matrix commands}@dots{}]@dots{} +[@t{ELSE} + @dots{}@i{matrix commands}@dots{}] +@t{END IF}. + +@t{LOOP} [@i{var}=@i{first} @t{TO} @i{last} [@t{BY} @i{step}]] [@t{IF} @i{expression}]. + @dots{}@i{matrix commands}@dots{} +@t{END LOOP} [@t{IF} @i{expression}]. + +@t{BREAK}. +@end display + +@noindent +The following matrix commands support matrix input and output: + +@display +@t{READ} @i{variable}[(@i{index}[,@i{index}])] + [/@t{FILE}=@i{file}] + /@t{FIELD}=@i{first} @t{TO} @i{last} [@t{BY} @i{width}] + [/@t{SIZE}=@i{expression}] + [/@t{MODE}=@{@t{RECTANGULAR} @math{|} @t{SYMMETRIC}@}] + [/@t{REREAD}] + [/@t{FORMAT}=@i{format}]. +@t{WRITE} @i{expression} + [/@t{OUTFILE}=@i{file}] + /@t{FIELD}=@i{first} @t{TO} @i{last} [@t{BY} @i{width}] + [/@t{MODE}=@{@t{RECTANGULAR} @math{|} @t{TRIANGULAR}@}] + [/@t{HOLD}] + [/@t{FORMAT}=@i{format}]. +@t{GET} @i{variable}[(@i{index}[,@i{index}])] + [/@t{FILE}=@{@i{file} @math{|} @t{*}@}] + [/@t{VARIABLES}=@i{variable}@dots{}] + [/@t{NAMES}=@i{expression}] + [/@t{MISSING}=@{@t{ACCEPT} @math{|} @t{OMIT} @math{|} @i{number}@}] + [/@t{SYSMIS}=@{@t{OMIT} @math{|} @i{number}@}]. +@t{SAVE} @i{expression} + [/@t{OUTFILE}=@{@i{file} @math{|} @t{*}@}] + [/@t{VARIABLES}=@i{variable}@dots{}] + [/@t{NAMES}=@i{expression}] + [/@t{STRINGS}=@i{variable}@dots{}]. +@t{MGET} [/@t{FILE}=@i{file}] + [/@t{TYPE}=@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@}]. +@t{MSAVE} @i{expression} + /@t{TYPE}=@{@t{COV} @math{|} @t{CORR} @math{|} @t{MEAN} @math{|} @t{STDDEV} @math{|} @t{N} @math{|} @t{COUNT}@} + [/@t{OUTFILE}=@i{file}] + [/@t{VARIABLES}=@i{variable}@dots{}] + [/@t{SNAMES}=@i{variable}@dots{}] + [/@t{SPLIT}=@i{expression}] + [/@t{FNAMES}=@i{variable}@dots{}] + [/@t{FACTOR}=@i{expression}]. +@end display + +@noindent +The following matrix commands provide additional support: + +@display +@t{DISPLAY} [@{@t{DICTIONARY} @math{|} @t{STATUS}@}]. +@t{RELEASE} @i{variable}@dots{}. +@end display + +@subsection Introduction + +@code{MATRIX} and @code{END MATRIX} enclose a special @pspp{} +sub-language, called the matrix language. With few exceptions, matrix +language commands are independent of those in the enclosing @pspp{} +program. In addition, each @code{MATRIX@dots{}END MATRIX} is an +independent program in the matrix language + +The matrix language works with matrices, where a @dfn{matrix} is a +rectangular array of real numbers. An @math{@var{n}@times{}@var{m}} +matrix has @var{n} rows and @var{m} columns. Some special cases are +important: a @math{@var{n}@times{}1} matrix is a @dfn{column vector}, +a @math{1@times{}@var{n}} is a @dfn{row vector}, and a +@math{1@times{}1} matrix is a @dfn{scalar}. + +The matrix language has limited support for matrices that contain +short strings instead of numbers. Each entry in a string matrix is 8 +bytes in size, with longer strings truncated and shorter strings +padded with spaces. String matrices are mainly useful for labeling +rows and columns when printing numerical matrices with the +@code{MATRIX PRINT} command. Arithmetic operations on string matrices +will not produce useful results. The user should not mix strings and +numbers within a matrix. + +The matrix language does not work with cases. A variable in the +matrix language represents a single matrix. + +The matrix language does not support missing values. + diff --git a/doc/pspp.texi b/doc/pspp.texi index 6c4771e944..26550b763e 100644 --- a/doc/pspp.texi +++ b/doc/pspp.texi @@ -90,6 +90,12 @@ graphic user interface @end quotation @end macro +@ifnottex +@macro times{} +× +@end macro +@end ifnottex + @c A macro to indicate variable names used in examples. @c NOT metasyntactical variables - for that use @var @macro exvar{VAR} -- 2.30.2