[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[groff] 20/49: doc/groff.texi: Introduce Texinfo @deffn notation.

From: G. Branden Robinson
Subject: [groff] 20/49: doc/groff.texi: Introduce Texinfo @deffn notation.
Date: Sun, 25 Sep 2022 17:02:57 -0400 (EDT)

gbranden pushed a commit to branch master
in repository groff.

commit cc0a808a9c141b94cb2653c2a99db8d2436f6dc3
Author: G. Branden Robinson <>
AuthorDate: Tue Sep 20 12:52:15 2022 -0500

    doc/groff.texi: Introduce Texinfo @deffn notation.
 doc/groff.texi  |  16 ++++++
 man/ | 158 ++++++++++++++++++++++++++++++++++++++++++++------------
 2 files changed, 141 insertions(+), 33 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index ee935552a..bbbbcda1d 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -795,6 +795,22 @@ system, and the command of that name.  In the first sense, 
 is an extended dialect of the @code{roff} language, for which many
 similar implementations exist.
+The @code{roff} language features several major categories for which
+many items are predefined.  Presentations of these items feature the
+form in which the item is most commonly used on the left, and, aligned
+to the right margin, the name of the category in brackets.
+@deffn Register \n[example]
+The register @samp{example} is one that that @code{groff} @emph{doesn't}
+predefine.  You can create it yourself, though; see @ref{Setting
+@end deffn
+To make this document useful as a reference and not merely amiable
+bedtime reading, we tend to present these syntax items in exhaustive
+detail when they arise.  References to topics discussed later in the
+text are frequent; skip material you don't understand yet.
 We use Texinfo's ``result'' (@result{}) and @error{} notations to
 present output written to the standard output and standard error
 streams, respectively.  Diagnostic messages from the GNU @code{troff}
diff --git a/man/ b/man/
index 77923c598..2b64715df 100644
--- a/man/
+++ b/man/
@@ -1602,40 +1602,122 @@ an increment or decrement is applied as if to\~0.
 .SH Requests
 .\" ====================================================================
-.IR groff ,
+.\" XXX: This is more of a groff_diff(7) sort of observation.
+.IR troff , \" GNU
 identifier names,
 including those of requests,
 can be arbitrarily long.
-No bracketing or marking of long names is needed in request invocation
+Unlike register and string interpolations,
+long request names require no specialized syntax.
+.\" BEGIN Keep (roughly) parallel with groff.texi node "Requests".
+Invoke a request by specifying its name after a control character and
+zero or more spaces or tabs.
+The invocation of an unrecognized request is interpreted as a macro
+Defining a macro with the same name as a request replaces the request.
+Deleting a request name with the
+.request .rm
+request makes it unavailable.
+Requests can be aliased with
+.request .als ,
+permitting them to be wrapped or non-destructively replaced.
 Most requests take one or more arguments.
-Tabs are permitted after a request name,
-before its first argument
+Tabs are permitted after a request name and before its first argument
 (if any),
 but arguments themselves must be separated only by space characters.
+.I troff \" Plan 9
+allows tabs to separate arguments.)
 There is no inherent limit on argument length or quantity.
+a space
+.I within
+a request argument is not relevant,
+not meaningful,
+or is supported by bespoke provisions,
+as with the
+.request .tl
+request's delimiters.
+Some requests,
+.request .ds ,
+interpret the remainder of the control line as a single argument.
-Not all details of request behavior are outlined here.
+Since spaces and tabs are ignored after a control character,
+they are commonly used to structure the source of documents or macro
+files with indentation.
-Refer to the
-.I groff
-Texinfo manual or
-.MR groff_diff @MAN7EXT@ .
+To prevent interpretation of a control character as such,
+prefix it with
+.RB \[lq] \[rs]& \[rq].
+Since a control character is recognized only at the beginning of an
+input line or the branch of a control structure such as the
+.request .if
+this dummy character
+(or non-printing input break)
+evades that special context without affecting the output.
+Test the
+.register .br
+register inside a macro definition to determine which control character
+was used when calling it.
+There is no way to invoke an undefined request;
+such syntax is interpreted as a macro call instead.
+If a macro of the desired name does not exist,
+it is created,
+assigned an empty definition,
+and a warning in category
+.B mac
+is emitted.
+Calling an undefined macro
+.I does
+end a macro definition naming it as its end macro.
+.\" END Keep (roughly) parallel with groff.texi node "Requests".
 .\" ====================================================================
 .SS "Request short reference"
 .\" ====================================================================
+Not all details of each request's behavior are outlined here.
+Refer to the
+.I groff
+Texinfo manual or
+.MR groff_diff @MAN7EXT@ .
@@ -3544,23 +3626,40 @@ to the stream named
-Besides these standard groff requests, there might be further macro
-They can originate from a macro package (see
-.MR roff @MAN7EXT@
-for an overview) or from a preprocessor.
-. 6v
+.\" ====================================================================
+.SH "Preprocessor tokens"
+.\" ====================================================================
 Most preprocessors enclose content between a pair of characteristic
+Such a token must occur at the beginning of an input line and use the
+dot control character.
+Spaces and tabs must not follow the control character or precede the
+end of the input line.
+Deviating from these rules defeats a token's recognition by the
+Tokens are generally preserved in preprocessor output and interpreted as
+macro calls subsequently by
+.IR @g@troff .
+.I @g@ideal
+preprocessor is not yet available in
+.IR groff .
 box, center, tab (^);
 c | c | c
 CfCB | CfCB | CfCB.
-preprocessor^start macro^ end macro
+preprocessor^starting token^ending token
@@ -3574,7 +3673,6 @@ grap^.G1^.G2
 glilypond^.lilypond start^.lilypond stop
@@ -3583,14 +3681,6 @@ gpinyin^.pinyin start^.pinyin stop
-.I @g@ideal
-preprocessor is not available in
-.I groff
 .\" ====================================================================
 .SH "Escape sequences"
 .\" ====================================================================
@@ -3716,6 +3806,8 @@ except for those defined as infix operators in numerical 
 about which more below.
 . 2v
 The following escape sequences are handled similarly to characters since
 they don't take arguments and thus are allowed as delimiters:
@@ -4623,7 +4715,7 @@ formatted in a dummy environment.
 .ESCq x N
-Increase required line space by
+Increase vertical spacing of current output line by
 .IR N \~vees
 (or specified units;
 negative before,
@@ -5006,8 +5098,8 @@ is active.
 .REG .br
-Within a macro, set to\~1 if macro called with the \[oq]normal\[cq]
-control character, and to\~0 otherwise.
+Interpolates\~1 if the currently executing macro was called using the
+normal control character and\~0 otherwise.
 .REG .c

reply via email to

[Prev in Thread] Current Thread [Next in Thread]