gbranden pushed a commit to branch master
in repository groff.
commit 8ab7cd1c71f5b895414b9b9fb1e7d856e30118b3
Author: G. Branden Robinson <[email protected]>
AuthorDate: Thu Sep 26 22:28:37 2024 -0500
[doc,man]: Consistently present contents req args.
Also fix two cases of missing dots before request names.
---
doc/groff.texi.in | 40 ++++++++++++++++++++++----------------
man/groff.7.man | 37 ++++++++++++-----------------------
man/groff_diff.7.man | 54 +++++++++++++++++-----------------------------------
3 files changed, 53 insertions(+), 78 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 4daf82e15..6f1881c59 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -11354,15 +11354,16 @@ Define an ordinary or special character@tie{}@var{c}
as @var{contents}.
If @var{contents} is absent, an existing character definition made with
the same request is deleted.
+A leading neutral double quote in the second argument is stripped from
+it, allowing embedded leading spaces in @var{contents}, which is read to
+the end of the input line in copy mode.
+
Defining (or redefining) a character @var{c} creates a formatter object
that is recognized like any other ordinary or special character on
input, and produces @var{contents} on output. Every time @var{c} is to
be output, @var{contents} is processed in a temporary environment and
-the result encapsulated in a node.@footnote{@xref{Gtroff Internals}.} A
-leading neutral double quote in the final argument is stripped from it,
-allowing embedded leading spaces in @var{contents}, which is read in
-copy mode and continues to the end of the input line. Further,
-compatibility mode is disabled and the escape character set to @code{\}
+the result encapsulated in a node.@footnote{@xref{Gtroff Internals}.}
+Compatibility mode is disabled and the escape character set to @code{\}
while @var{contents} is interpreted. Any emboldening, constant spacing,
or track kerning is applied to this object rather than to individual
glyphs in @var{contents}.
@@ -12744,7 +12745,10 @@ can be manipulated through renaming, removal, and
aliasing (@code{rn},
@cindex mode, copy, and @code{length} request
Compute the number of characters of @var{anything} and store the count
in the register @var{reg}. If @var{reg} doesn't exist, it is created.
-GNU @command{troff} reads @var{anything} in copy mode.
+
+A leading neutral double quote in the argument is stripped from it,
+allowing embedded leading spaces in @var{contents}, which is read to
+the end of the input line in copy mode.
@Example
.ds xxx abcd\h'3i'efgh
@@ -15741,10 +15745,11 @@ no output at all; its argument is simply ignored.
@cindex mode, copy, and @code{output} request
@Defreq {output, [@code{"}]@Var{contents}}
Emit @var{contents} directly to GNU @command{troff}'s output; this usage
-is similar to that of @code{\!} in the top-level diversion. An initial
-neutral double quote in the argument is stripped, allowing embedded
-leading spaces in @var{contents}, which is read in copy mode and
-continues to the end of the input line.
+is similar to that of @code{\!} in the top-level diversion.
+
+A leading neutral double quote in the argument to @code{output} is
+stripped from it, allowing embedded leading spaces in @var{contents},
+which is read to the end of the input line in copy mode.
@strong{Caution:@:} Use of these features can put syntactically invalid
content into GNU @command{troff}'s output, which @code{groff}'s output
@@ -16542,10 +16547,12 @@ standard error stream; @ref{Debugging}.
@cindex write to file stream (@code{write}, @code{writec})
@cindex file stream, write to (@code{write}, @code{writec})
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 subject of an @code{open} (or @code{opena}) request. GNU
+@command{troff} flushes the stream after writing to it.
+
+A leading neutral double quote in the second argument is stripped from
+it, allowing embedded leading spaces in @var{contents}, which is read to
+the end of the input line in copy mode.
The @code{writec} request is like @code{write}, but only @code{write}
appends a newline to @var{contents}.
@@ -16625,8 +16632,9 @@ Embed @var{contents} into GNU @command{troff} output as
parameters to an
The interpretation of such parameters is determined by the output driver
or other postprocessor.
-The @code{device} request strips a leading neutral double quote from
-@var{contents} to allow embedding of leading spaces.
+A leading neutral double quote in the argument to @code{device} is
+stripped from it, allowing embedded leading spaces in @var{contents},
+which is read to the end of the input line in copy mode.
@cindex @code{device} request, and copy mode
@cindex copy mode, and @code{device} request
diff --git a/man/groff.7.man b/man/groff.7.man
index 7e3bf0431..c425d216b 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2775,18 +2775,12 @@ Remove definition of ordinary or special
.RI character\~ c.
.
.TPx
-.REQ .char "c contents"
+.REQ .char "c \fR[\fB\[dq]\fP]\fIcontents"
Define ordinary or special character
.I c
as
.I anything.
.
-A leading neutral double quote in the second argument is stripped from
-it,
-allowing embedded leading spaces in
-.I contents,
-which is read in copy mode and continues to the end of the input line.
-.
.TPx
.REQ .chop name
Remove the last character from the macro,
@@ -3023,7 +3017,7 @@ As
with compatibility mode disabled when the macro is interpreted.
.
.TPx
-.REQ .device contents
+.REQ .device \fR[\fB"\fP]\fIcontents
Write
.IR contents ,
read in copy mode,
@@ -3031,9 +3025,6 @@ to
.I @g@troff
output as a device extension command.
.
-A leading neutral double quote is stripped to allow embedding of
-leading spaces.
-.
.TPx
.REQ .devicem name
Write contents of macro or string
@@ -3282,7 +3273,7 @@ as
.IR contents .
.
As
-.request char ,
+.request .char ,
but a character defined by
.B fschar
is located after the list of fonts declared with
@@ -3630,9 +3621,9 @@ Set leader repetition character
.RB \[lq] . \[rq]).
.
.TPx
-.REQ .length "reg anything"
+.REQ .length "reg \fR[\fB\[dq]\fP]\fIcontents"
Compute the number of characters in
-.I anything
+.I contents
and store the count
in the register
.IR reg .
@@ -3947,18 +3938,14 @@ Output vertical distance that was saved by the
request.
.
.TPx
-.REQ .output contents
+.REQ .output \fR[\fB"\fP]\fIcontents
Emit
.I contents
-directly to
+\[lq]transparently\[rq]
+(directly) to
.IR @g@troff 's
output.
.
-A leading neutral double quote in the argument is stripped,
-allowing embedded leading spaces in
-.IR contents ,
-which is read in copy mode and continues to the end of the input line.
-.
.TPx
.REQ .pc
Reset page number character to\~\c
@@ -4293,7 +4280,7 @@ as
.IR contents .
.
As
-.request char ,
+.request .char ,
but a character defined with
.B schar
is located after the list of fonts declared with the
@@ -4795,7 +4782,7 @@ to
which must previously have been the subject of an
.request .open
(or
-.request .opena )
+.request \%.opena )
request,
followed by a newline.
.
@@ -4822,9 +4809,9 @@ Write the contents of the macro or string
to
.IR stream ,
which must previously have been the subject of an
-.request open
+.request .open
(or
-.request \%opena )
+.request \%.opena )
request.
.
The contents of
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index f2c93574b..daeddd268 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -1511,6 +1511,11 @@ accepting an optional leading neutral double-quote
in an argument that extends to the end of the input line,
permitting inclusion of leading spaces.
.
+Such arguments are labeled
+.I contents,
+are read in copy mode,
+and cosume the rest of the input line.
+.
.
.TP 8n \" ".break" + 2n
.BI .aln\~ "new old"
@@ -2010,14 +2015,7 @@ the
.I groff
Texinfo manual.)
.
-A leading neutral double quote in the second argument is stripped from
-it,
-allowing embedded leading spaces in
-.I contents,
-which is read in copy mode and continues to the end of the input line.
-.
-Further,
-compatibility mode is disabled and the escape character set
+Compatibility mode is disabled and the escape character set
.RB to\~ \[rs]
while
.I contents
@@ -2350,7 +2348,9 @@ is interpreted.
.
.
.TP
-.BI .device\~ contents
+.BR .device\~ [\c
+.RB [ \[dq] ]\c
+.IR contents ]
Write
.IR contents ,
read in copy mode,
@@ -2358,11 +2358,6 @@ to
.I @g@troff
output as a device extension command.
.
-A leading neutral double quote in
-.I anything
-is stripped to allow the embedding of
-leading spaces.
-.
.
.TP
.BI .devicem\~ name
@@ -3070,9 +3065,11 @@ is omitted.
.
.
.TP
-.BI .length\~ "reg anything"
+.BI .length\~ reg\~\c
+.RB [[ \[dq]\c
+.IR contents ]
Compute the number of characters in
-.I anything
+.I contents
and store the count in the register
.IR reg .
.
@@ -3081,12 +3078,6 @@ If
doesn't exist,
it is created.
.
-GNU
-.I troff \" GNU
-reads
-.I anything
-in copy mode.
-.
.
.TP
.BR .linetabs\~ [\c
@@ -3240,18 +3231,14 @@ append to it instead of truncating it.
.IR contents ]
Emit
.I contents
-directly to
+\[lq]transparently\[rq]
+(directly) to
.IR @g@troff 's
output;
this usage is similar to that of
.B \[rs]!\&
in the top-level diversion.
.
-A leading neutral double quote in the argument is stripped,
-allowing embedded leading spaces in
-.IR contents ,
-which is read in copy mode and continues to the end of the input line.
-.
.
.TP
.B .pcolor
@@ -3742,8 +3729,7 @@ the increase in width is a linear function of the type
size.
.
.
.TP
-.BR .tm1\~ [\c
-.RI [ \[dq] ]\c
+.BR .tm1 \~[[ \[dq] ]\c
.IR message ]
As
.BR tm ,
@@ -3753,8 +3739,7 @@ allowing embedded leading spaces in
.
.
.TP
-.BR .tmc\~ [\c
-.RI [ \[dq] ]\c
+.BR .tmc \~[[ \[dq] ]\c
.IR message ]
As
.B tm1
@@ -4005,11 +3990,6 @@ which must previously have been the subject of an
request,
followed by a newline.
.
-A leading neutral double quote in the second argument is stripped,
-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.
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
