gbranden pushed a commit to branch master
in repository groff.
commit 7d8dfc13982b55dfc06262fd05467d6dc94897e8
Author: G. Branden Robinson <[email protected]>
AuthorDate: Fri Mar 27 20:35:42 2026 -0500
[doc,man]: Recast and sync introductory material.
* Drop sentence that is unnecessary in an intro.
* Favor active voice over passive.
---
doc/groff.texi.in | 14 ++++++--------
man/roff.7.man | 27 ++++++++++++---------------
2 files changed, 18 insertions(+), 23 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index d02b857e1..6708a1f8c 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -6260,15 +6260,13 @@ Requests often take
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
+permitting extension or override
+of the request repertoire.@footnote{Argument handling in macros
is more flexible but also more complex.
@xref{Calling Macros}.}
@@ -6276,9 +6274,9 @@ is more flexible but also more complex.
@cindex macro
@cindex calling macros (introduction)
@cindex interpolation
-A
+Think of a
@dfn{macro}
-can be thought of as an abbreviation you can define
+as an abbreviation you can define
for a collection of control and text lines.
When a document
@dfn{calls}
@@ -6288,9 +6286,9 @@ the formatter replaces the control line with the macro's
definition.
The process of textual replacement is known as
@dfn{interpolation}.@footnote{Some escape sequences undergo
interpolation as well.}
-Interpolations are handled as soon as they are recognized,
+The formatter performs an interpolation upon recognition,
and once performed,
-the formatter scans the replacement for further requests,
+it scans the replacement for further requests,
macro calls,
and escape sequences.
diff --git a/man/roff.7.man b/man/roff.7.man
index b21ced3dc..3b9b1b2bf 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -500,9 +500,6 @@ 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.
-.
.\" TODO: We haven't introduced escape sequences yet.
Requests and escape sequences comprise the control language
of the formatter.
@@ -510,31 +507,31 @@ 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.
+permitting extension or override
+of the request repertoire.
.
(Argument handling in macros is more flexible but also more complex.)
.\" @xref{Calling Macros}.
.
.
.P
-A
+Think of a
.I macro
-can be thought of as an abbreviation you can define for a
-collection of control and text lines.
+as an abbreviation you can define
+for a collection of control and text lines.
.
-When the macro is
-.I called
-by giving its name after a control character,
-it is replaced with what it stands for.
+When a document
+.I calls
+a macro
+by placing its name after a control character,
+the formatter replaces the control line with the macro's definition.
.
The process of textual replacement is known as
.I interpolation.
.\" @footnote{Some escape sequences undergo interpolation as well.}
-Interpolations are handled as soon as they are recognized,
+The formatter performs an interpolation upon recognition,
and once performed,
-a
-.I roff
-formatter scans the replacement for further requests,
+it scans the replacement for further requests,
macro calls,
and escape sequences.
.
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
