[groff] 39/49: roff(7): Add "Requests and macros" subsection.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 2a9165be68a9d1ca72f09f57a6e1c1b1bf20dfab
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Sep 25 13:17:54 2022 -0500

    roff(7): Add "Requests and macros" subsection.
    
    This largely mirrors the node of the same name in our Texinfo manual.
    
    Rename "Language elements" subsection to "Other language elements" since
    the latter no longer tries to be comprehensive.  Drop concepts now
    introduced in the above material.
---
 man/roff.7.man | 177 +++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 108 insertions(+), 69 deletions(-)

diff --git a/man/roff.7.man b/man/roff.7.man
index e67722a23..762aeb893 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -365,6 +365,113 @@ preprocessor for table construction.
 .
 .
 .\" ====================================================================
+.SS "Requests and macros"
+.\" ====================================================================
+.
+.\" BEGIN Keep roughly parallel with groff.texi node "Requests and
+.\" Macros".
+.\" We have now encountered almost all of the syntax there is in the
+.\" @code{roff} language, with an exception already noted in passing.
+A
+.I request
+is an instruction to the formatter that occurs after a
+.I control character,
+which is recognized at the beginning of an input line.
+.
+The regular control character is a dot
+.RB \[lq] .\& \[rq].
+.
+Its counterpart,
+the
+.I no-break control character,
+a neutral apostrophe
+.RB \[lq] \|\[aq]\| \[rq],
+suppresses the break
+.\" slack wording: that is
+implied by some requests.
+.
+These characters were chosen because it is uncommon for lines of text in
+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 non-printing input break
+escape sequence,
+.RB \[lq] \[rs]& \[rq].
+.
+.
+.P
+An input line beginning with a control character is called a
+.I control line.
+.
+Every line of input that is not a control line is a
+.I text line.
+.
+.
+.P
+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.
+.
+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.
+.
+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}.}
+.
+.
+.P
+A
+.I macro
+can be thought of 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.
+.
+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,
+and once performed,
+a
+.I roff
+formatter scans the replacement for further requests,
+macro calls,
+and escape sequences.
+.
+.
+.P
+In
+.I roff
+systems,
+the
+.RB \[lq] de \[rq]
+request defines a macro.
+.\" @footnote{GNU @code{troff} offers additional ones.  @xref{Writing
+.\" Macros}.}
+.\" END Keep roughly parallel with groff.texi node "Requests and
+.\" Macros".
+.
+.
+.\" ====================================================================
 .SS "Page geometry"
 .\" ====================================================================
 .
@@ -519,55 +626,9 @@ or at least bear vertical margins larger than one vee.
 .
 .
 .\" ====================================================================
-.SS "Language elements"
+.SS "Other language elements"
 .\" ====================================================================
 .
-Lines of input to any
-.I roff
-formatter can be classified as one of two types:
-control lines and text lines.
-.
-.
-.P
-A
-.I control line
-starts with the
-.I control character,
-a dot
-.RB ( .\& )
-or the
-.I no-break control character,
-a neutral apostrophe
-.RB ( \[aq] ).
-.
-Either control character is followed by zero or more spaces or tabs
-and then an optional
-.I request,
-an instruction built in to the formatter.
-.
-Some requests take one or more
-.I arguments,
-which follow on the same line,
-separated from the request name and each other only by spaces.
-.
-.
-.P
-Any input line that is not a control line is a
-.I text line.
-.
-See section \[lq]Line continuation\[rq] in
-.MR groff @MAN7EXT@
-for an exception to this rule.
-.
-Text lines generally become formatted output.
-.
-To start a text line with the control or no-break control character,
-prefix the character with the
-.B \[rs]&
-escape sequence.
-.
-.
-.P
 .I Escape sequences
 start with the
 .I escape character,
@@ -586,28 +647,6 @@ escape sequence recognition can be turned off and back on.
 .
 .
 .P
-.I Macros
-permit the extension or replacement of the request repertoire.
-.
-Certain requests can be invoked to define a macro,
-a user-directed abbreviation for a collection of input lines.
-.
-Macros are called on control lines much as requests are invoked,
-albeit with occasional differences in argument handling.
-.
-When a macro is called,
-its definition
-(or \[lq]body\[rq])
-is
-.I interpolated,
-as if typed at its call site.
-.
-Its contents are then parsed for further request invocations,
-macro calls,
-and escape sequences.
-.
-.
-.P
 .I Strings
 store character sequences.
 .