gbranden pushed a commit to branch master
in repository groff.
commit 187a177216e716bd29c7f3c0bf5060f66c7d26bc
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun Jan 4 06:34:58 2026 -0600
[doc,man]: Tweak introductory material.
Generalize statements that are not GNU troff-specific.
Refer to GNU troff, the program, with Texinfo's "command" command
instead of "code".
Also break input lines in a roff-friendly way.
---
doc/groff.texi.in | 94 ++++++++++++++++++++++++++++++++++++-------------------
man/roff.7.man | 42 +++++++++++--------------
2 files changed, 79 insertions(+), 57 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index a742e03d6..55159249d 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -5887,7 +5887,7 @@ see @ref{Manipulating Filling and Adjustment}.
@cindex character, leader
@cindex tab stops
@cindex stops, tab
-GNU @code{troff} translates input horizontal tab characters (``tabs'')
+The formatter translates input horizontal tab characters (``tabs'')
and @key{Control+A} characters (``leaders'') into movements to the next
tab stop. Tabs simply move to the next tab stop; leaders place enough
periods to fill the space. Tab stops are by default located every half
@@ -5943,30 +5943,39 @@ These characters were chosen because it is uncommon for
lines of text in
natural languages to begin with them.
@cindex dummy character (@code{\&}), as control character suppressor
@cindex character, dummy (@code{\&}), as control character suppressor
-If you require a formatted period or apostrophe (closing single
-quotation mark) where GNU @code{troff} is expecting a control character,
-prefix the dot or neutral apostrophe with the dummy character escape
-sequence, @samp{\&}.
+If you require a formatted period or apostrophe
+(closing single quotation mark)
+where the formatter expects a control character,
+prefix the dot or neutral apostrophe
+with the dummy character escape sequence,
+@samp{\&}.
@cindex control line
An input line beginning with a control character is called a
@dfn{control line}.
@cindex text line
-Every line of input that is not a control line is a @dfn{text
-line}.@footnote{The @code{\@key{RET}} escape sequence can alter how an
-input line is classified; see @ref{Line Continuation}.}
+Every line of input that is not a control line is a
+@dfn{text line}.@footnote{The @code{\@key{RET}} escape sequence
+can alter how an input line is classified;
+see @ref{Line Continuation}.}
@cindex argument
-Requests often take @dfn{arguments}, words (separated from the request
-name and each other by spaces) that specify details of the action GNU
-@code{troff} is expected to perform. If a request is meaningless
-without arguments, it is typically ignored.
-
-GNU @code{troff}'s requests and escape sequences comprise the control
-language of the formatter. Of key importance are the requests that
-define macros. Macros are invoked like requests, enabling the request
-repertoire to be extended or overridden.@footnote{Argument handling in
-macros is more flexible but also more complex. @xref{Calling Macros}.}
+Requests often take
+@dfn{arguments},
+words
+(separated from the request name and each other by spaces)
+that specify details of the action you expect the formatter to perform.
+If a request is meaningless without arguments,
+it is typically ignored.
+
+Requests and escape sequences comprise the control language
+of the formatter.
+Of key importance are the requests that define macros.
+Macros are invoked like requests,
+enabling the request repertoire
+to be extended or overridden.@footnote{Argument handling in macros
+is more flexible but also more complex.
+@xref{Calling Macros}.}
@anchor{Macros} @c 1.22.4
@cindex macro
@@ -5990,9 +5999,15 @@ the formatter scans the replacement for further requests,
macro calls,
and escape sequences.
-In @code{roff} systems, the @code{de} request defines a
-macro.@footnote{GNU @code{troff} offers additional ones. @xref{Writing
-Macros}.}
+In
+@code{roff}
+systems,
+the
+@code{de}
+request defines a macro.@footnote{GNU
+@command{troff}
+offers additional ones.
+@xref{Writing Macros}.}
@Example
.de DATE
@@ -6404,14 +6419,24 @@ Euro @samp{\[Eu]} and per mille @samp{\[%0]} glyphs.}
@cindex input conventions
@cindex conventions for input
-Since GNU @code{troff} fills text automatically, it is common practice
-in the @code{roff} language to avoid visual composition of text in input
-files: the esthetic appeal of the formatted output is what matters.
-Therefore, @code{roff} input should be arranged such that it is easy for
-authors and maintainers to compose and develop the document, understand
-the syntax of @code{roff} requests, macro calls, and preprocessor
-languages used, and predict the behavior of the formatter. Several
-traditions have accrued in service of these goals.
+Since a
+@code{roff}
+formatter fills text automatically,
+its experienced users tend to avoid visual composition
+of text in input files:
+the esthetic appeal of the formatted output is what matters.
+Therefore,
+@code{roff}
+input should be arranged
+such that it is easy for authors and maintainers
+to compose and develop the document,
+understand the syntax of
+@code{roff}
+requests,
+macro calls,
+and preprocessor languages used,
+and predict the behavior of the formatter.
+Several traditions have accrued in service of these goals.
@itemize @bullet
@item
@@ -6463,10 +6488,13 @@ region option
causes the program to ignore spaces at the boundaries of table cells.)
@item
-Comment your document. It is never too soon to apply comments to
-record information of use to future document maintainers (including your
-future self). We thus introduce another escape sequence, @code{\"},
-which causes GNU @code{troff} to ignore the remainder of the input line.
+Comment your document.
+It is never too soon to apply comments
+to record information of use to future document maintainers
+(including your future self).
+We thus introduce another escape sequence,
+@code{\"},
+which causes the formatter to ignore the remainder of the input line.
@item
Use the empty request---a control character followed immediately by a
diff --git a/man/roff.7.man b/man/roff.7.man
index dfb51f197..335ac7b43 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -447,10 +447,9 @@ natural languages to begin with them.
If you require a formatted period or apostrophe
(closing single quotation mark)
where
-.\" GNU @code{troff}
-the formatter is expecting a control character,
-prefix the dot or neutral apostrophe with the dummy character escape
-sequence,
+the formatter expects a control character,
+prefix the dot or neutral apostrophe
+with the dummy character escape sequence,
.RB \[lq] \[rs]& \[rq].
.
.
@@ -467,23 +466,22 @@ Requests often take
.I arguments,
words
(separated from the request name and each other by spaces)
-that specify details of the action
-.\" GNU @code{troff}
-the formatter is expected to perform.
+that specify details of the action you expect the formatter to perform.
.
If a request is meaningless without arguments,
it is typically ignored.
.
-.\" TODO: roff(7): We haven't introduced escape sequences yet.
-.\" GNU @code{troff}'s requests and escape sequences comprise the
-.\" control language of the formatter.
+.\" TODO: We haven't introduced escape sequences yet.
+Requests and escape sequences comprise the control language
+of the formatter.
.
Of key importance are the requests that define macros.
.
Macros are invoked like requests,
enabling the request repertoire to be extended or overridden.
-.\" @footnote{Argument handling in macros is more flexible but also more
-.\" complex. @xref{Calling Macros}.}
+.
+(Argument handling in macros is more flexible but also more complex.)
+.\" @xref{Calling Macros}.
.
.
.P
@@ -2120,12 +2118,11 @@ suffix.
.SH "Input conventions"
.\" ====================================================================
.
-Since
-.I @g@troff
-fills text automatically,
-it is common practice in the
+Since a
.I roff
-language to avoid visual composition of text in input files:
+formatter fills text automatically,
+its experienced users tend to avoid visual composition
+of text in input files:
the esthetic appeal of the formatted output is what matters.
.
Therefore,
@@ -2137,8 +2134,7 @@ understand the syntax of
requests,
macro calls,
and preprocessor languages used,
-and predict the behavior of the
-formatter.
+and predict the behavior of the formatter.
.
Several traditions have accrued in service of these goals.
.
@@ -2221,16 +2217,14 @@ causes the program to ignore spaces at the boundaries
of table cells.)
.IP \[bu]
Comment your document.
.
-It is never too soon to apply comments to record information of use to
-future document maintainers
+It is never too soon to apply comments
+to record information of use to future document maintainers
(including your future self).
.\" Texinfo: We thus introduce another escape sequence, @code{\"}, which
The
.B \[rs]\[dq]
escape sequence
-causes
-.I @g@troff
-to ignore the remainder of the input line.
+causes the formatter to ignore the remainder of the input line.
.
.
.IP \[bu]
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
