gbranden pushed a commit to branch master
in repository groff.
commit a832f8ca080f157450dd1cdf20c5906b777f6efe
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sat Jan 10 19:41:16 2026 -0600
[doc,man]: Edit "Host System Service Access".
* Relocate `pi` request example earlier, to sit alongside relevant
narrative.
* Refer to GNU troff, the program, with Texinfo's "command" command
instead of "code".
* Kick forward reference into a footnote.
* Favor active voice over passive.
* Discuss `-U` option consistently.
* Break input lines in a roff-friendly way.
---
doc/groff.texi.in | 76 +++++++++++++++++++++++++++++++++++-----------------
man/groff.7.man | 6 +++--
man/groff_diff.7.man | 8 +++---
3 files changed, 61 insertions(+), 29 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index fea243bb3..4ea6239a2 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -19605,6 +19605,14 @@ Multiple
requests construct a multi-stage pipeline
in the same order as the formatter encounters the requests.
+@Example
+.pi foo
+.pi bar
+@endExample
+
+is the same as
+@w{@samp{.pi foo | bar}}.
+
@code{pi}
must be invoked before
GNU
@@ -19650,14 +19658,6 @@ which
output drivers then fail to process.
The pipeline you construct is responsible
for maintaining the validity of the input to the output driver.
-
-@Example
-.pi foo
-.pi bar
-@endExample
-
-is the same as
-@w{@samp{.pi foo | bar}}.
@endDefreq
@cindex system commands, running
@@ -19674,9 +19674,14 @@ The formatter does not capture the output produced by
the command(s).
@cindex mode, safer
@cindex unsafe mode
@cindex mode, unsafe
-It is an error to use this request in safer mode; this is the default.
-Give GNU @code{troff} or a front end program the @option{-U} option to
-enable unsafe mode.
+It is an error to use this request in safer mode;
+this is the default.
+Give
+GNU
+@command{troff} @c GNU
+or a front end program the
+@option{-U}
+command-line option to enable unsafe mode.
@cindex @code{system()} return value register (@code{systat})
The writable register @code{systat} contains the return value of the
@@ -19739,12 +19744,19 @@ if it already exists instead of overwriting it.
@cindex mode, safer
@cindex unsafe mode
@cindex mode, unsafe
-It is an error to use these requests in safer mode; this is the default.
-Give GNU @code{troff} or a front end program the @option{-U} option to
-enable unsafe mode.
+It is an error to use these requests in safer mode;
+this is the default.
+Give
+GNU
+@command{troff} @c GNU
+or a front end program the
+@option{-U}
+command-line option to enable unsafe mode.
-The @code{pstream} request dumps the list of open streams to the
-standard error stream; see @ref{Debugging}.
+The
+@code{pstream}
+request dumps the list of open streams
+to the standard error stream.@footnote{@xref{Debugging}.}
@endDefreq
@DefreqList {write, stream [@code{"}]@Var{contents}}
@@ -19766,17 +19778,33 @@ appends a newline to @var{contents}.
@Defreq {writem, stream name}
@cindex @code{asciify} request, and @code{writem}
-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.
+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
-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.
+GNU
+@command{troff} @c GNU
+reads the contents of
+@var{name}
+in copy mode.
+That is,
+it ignores already formatted elements (nodes).
+Consequently,
+diversions must be unformatted with
+the
+@code{asciify}
+request before calling
+@code{writem}.
+Usually,
+this means a loss of information.
@endDefreq
@Defreq {close, stream}
diff --git a/man/groff.7.man b/man/groff.7.man
index 24dd428cd..bd5e29bf3 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -5513,9 +5513,11 @@ which must previously have been the subject of an
.BR opena )
request.
.
-The contents of
+GNU
+.I troff \" GNU
+reads the contents of
.I name
-are read in copy mode.
+in copy mode.
.
.LE
.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 475c6a21e..80eb77dbc 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -4748,12 +4748,14 @@ to
which must previously have been the subject of an
.RB \[lq] open \[rq]
(or
-.BR \%opena )
+.BR opena )
request.
.
-The contents of
+GNU
+.I troff \" GNU
+reads the contents of
.I name
-are read in copy mode.
+in copy mode.
.
.
.br
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
