gbranden pushed a commit to branch master
in repository groff.
commit 8d1673c79c704092e1023682965881e41ff1b932
Author: G. Branden Robinson <[email protected]>
AuthorDate: Thu Sep 26 22:00:48 2024 -0500
[doc,man]: Clarify `write{,c,m}` request behavior.
---
doc/groff.texi.in | 16 +++++++++-------
man/groff.7.man | 19 +++++++++++++++++--
man/groff_diff.7.man | 9 ++++++++-
3 files changed, 34 insertions(+), 10 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 2a6c40d7e..bd274003f 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -16539,22 +16539,24 @@ Write @var{contents} to @var{stream}, which must
previously have been
the subject of an @code{open} request. A leading neutral double quote
in the second argument is stripped, allowing embedded leading spaces in
@var{contents}, which is read in copy mode until the end of the line.
+GNU @command{troff} flushes the stream after writing to it.
The @code{writec} request is like @code{write}, but only @code{write}
appends a newline to @var{contents}.
@endDefreq
-@Defreq {writem, stream xx}
+@Defreq {writem, stream name}
@cindex @code{asciify} request, and @code{writem}
-Write the contents of the macro or string @var{xx} to the file
-associated with the specified @var{stream}.
-
+Write the contents of the macro or string @var{name} to @var{stream},
+which must previously have been the subject of an @code{open} (or
+@code{opena}) request.
@cindex @code{writem} request, and copy mode
@cindex copy mode, and @code{writem} request
@cindex mode, copy, and @code{writem} request
-@var{xx} is read in copy mode, i.e., already formatted elements are
-ignored. Consequently, diversions must be unformatted with the
-@code{asciify} request before calling @code{writem}. Usually, this
+The contents of
+@var{name} are read in copy mode. That is, already formatted elements
+(nodes) are ignored. Consequently, diversions must be unformatted with
+the @code{asciify} request before calling @code{writem}. Usually, this
means a loss of information.
@endDefreq
diff --git a/man/groff.7.man b/man/groff.7.man
index efeaf5c12..7e3bf0431 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -4794,6 +4794,8 @@ to
.IR stream ,
which must previously have been the subject of an
.request .open
+(or
+.request .opena )
request,
followed by a newline.
.
@@ -4802,6 +4804,10 @@ allowing embedded leading spaces in
.IR contents ,
which is read in copy mode until the end of the line.
.
+GNU
+.I troff \" GNU
+flushes the stream after writing to it.
+.
.TPx
.REQ .writec "stream contents"
As
@@ -4811,10 +4817,19 @@ but does not append a newline to
.
.TPx
.REQ .writem "stream name"
-Write contents of macro or string
+Write the contents of the macro or string
.I name
to
-.IR stream .
+.IR stream ,
+which must previously have been the subject of an
+.request open
+(or
+.request \%opena )
+request.
+.
+The contents of
+.I name
+are read in copy mode.
.
.LE
.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index a006e8549..f2c93574b 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -4010,6 +4010,10 @@ allowing embedded leading spaces in
.IR contents ,
which is read in copy mode until the end of the line.
.
+GNU
+.I troff \" GNU
+flushes the stream after writing to it.
+.
.
.TP
.BI .writec\~ stream\~\c
@@ -4029,10 +4033,13 @@ to
.IR stream ,
which must previously have been the subject of an
.B open
+(or
+.B \%opena )
request.
.
+The contents of
.I name
-is read in copy mode.
+are read in copy mode.
.
.
.br
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
