From 830bb2913e1a8edb2b05b28726a5b647b9cc509e Mon Sep 17 00:00:00 2001
From: Ben Pfaff <blp@cs.stanford.edu>
Date: Fri, 19 Nov 2021 19:46:28 -0800
Subject: [PATCH] MATRIX WRITE examples.

---
 doc/matrices.texi | 47 +++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 41 insertions(+), 6 deletions(-)

diff --git a/doc/matrices.texi b/doc/matrices.texi
index 65dbd94b62..cceff9b997 100644
--- a/doc/matrices.texi
+++ b/doc/matrices.texi
@@ -2341,10 +2341,43 @@ command writes only the entries on and below the matrix's main
 diagonal.  Entries above the diagonal are not written.  Only square
 matrices may be written with @code{MODE=TRIANGULAR}.
 
-Ordinarily, each @code{WRITE} command starts a new line in the output
-file.  With @code{HOLD}, the next @code{WRITE} command will write to
-the same line as the current one.  This can be useful to write more
-than one matrix on a single output line.
+Ordinarily, each @code{WRITE} command writes complete lines to the
+output file.  With @code{HOLD}, the final line written by @code{WRITE}
+will be held back for the next @code{WRITE} command to augment.  This
+can be useful to write more than one matrix on a single output line.
+
+@subsubheading Example 1: Basic Usage
+
+This matrix program:
+
+@example
+WRITE {1, 2; 3, 4} /OUTFILE='matrix.txt' /FIELD=1 TO 80.
+@end example
+
+@noindent
+writes the following to @file{matrix.txt}:
+
+@example
+ 1 2
+ 3 4
+@end example
+
+@subsubheading Example 2: Triangular Matrix
+
+This matrix program:
+
+@example
+WRITE MAGIC(5) /OUTFILE='matrix.txt' /FIELD=1 TO 80 BY 5 /MODE=TRIANGULAR.
+@end example
+
+@noindent
+writes the following to @file{matrix.txt}:
+    17
+    23    5
+     4    6   13
+    10   12   19   21
+    11   18   25    2    9
+@example
 
 @node Matrix GET Command
 @subsection The @code{GET} Command
@@ -2570,8 +2603,10 @@ file (@pxref{Matrix Files}).
 The @code{TYPE} subcommand is required.  It specifies the
 @code{ROWTYPE_} to write along with this matrix.
 
-The @code{FACTOR} and @code{SPLIT} subcommands are required if and
-only if the matrix file has factor or split variables, respectively.
+The @code{FACTOR} and @code{SPLIT} subcommands are required on the
+first @code{MSAVE} if and only if the matrix file has factor or split
+variables, respectively.  After that, their values are carried along
+from one @code{MSAVE} command to the next in syntax order as defaults.
 Each one takes an expression that must evaluate to a vector with the
 same number of entries as the matrix has factor or split variables,
 respectively.  Each @code{MSAVE} only writes data for a single
-- 
2.30.2