gbranden pushed a commit to branch master
in repository groff.
commit e9c8e4f92659d00a8f86c2a58eaf25766fa1e7bf
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
AuthorDate: Fri Nov 10 12:44:04 2023 -0600
groff(7): Revise request short reference.
* Clarify application of compatibility mode to appendments to macros and
strings when using `am1`, `ami1`, and `as1`.
* Migrate to metasyntactic variable names introduced in section: `reg`,
`mac`, `str`, `ident`, `anything`, `div`,
* Use thin space escape sequence `\|` between double dots when
formatting the default ending syntax of a macro definition.
* Parallelize wording.
* Recast for clarity.
* Annotate some degenerate cases.
---
man/groff.7.man | 588 +++++++++++++++++++++++++-------------------------------
1 file changed, 267 insertions(+), 321 deletions(-)
diff --git a/man/groff.7.man b/man/groff.7.man
index b7b4fe476..a6b3dec17 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2411,13 +2411,11 @@ write
.I message
to the standard error stream and exit with failure status.
.
-.
.TPx
.REQ .ad
Enable output line alignment and adjustment using the mode stored in
.BR \[rs]n[.j] .
.
-.
.TPx
.REQ .ad c
Enable output line alignment and adjustment in mode
@@ -2428,13 +2426,12 @@ Enable output line alignment and adjustment in mode
Sets
.BR \[rs]n[.j] .
.
-.
.TPx
-.REQ .af "register c"
+.REQ .af "reg c"
Assign format
.I c
-to
-.IR register ,
+to register
+.I reg,
where
.I c
is
@@ -2480,93 +2477,113 @@ already exists,
its contents are lost unless already aliased.
.
.TPx
-.REQ .am "macro"
-Append to
-.I macro
-until
-.B ..\&
-is encountered.
+.REQ .am mac
+Append to macro
+.I mac
+until encountering
+.RB \[lq] .\|.\& \[rq].
.
.TPx
-.REQ .am "macro end"
-Append to
-.I macro
+.REQ .am "mac end-mac"
+Append to macro
+.I mac
until
-.BI . end
-is called.
+.I end-mac
+is called at the start of a control line in the current conditional
+block.
+.
+.I end-mac
+can be a request.
.
.TPx
-.REQ .am1 "macro"
-Same as
-.request .am
-but with compatibility mode switched off during macro expansion.
+.REQ .am1 mac
+As
+.request .am ,
+with compatibility mode disabled when the appendment to macro
+.I mac
+is interpreted.
.
.TPx
-.REQ .am1 "macro end"
-Same as
-.request .am
-but with compatibility mode switched off during macro expansion.
+.REQ .am1 "mac end-mac"
+As
+.RB \[lq] .am
+.IR mac \[rq],
+with compatibility mode disabled when the appendment to macro
+.I mac
+is interpreted.
.
.TPx
-.REQ .ami "macro"
-Append to a macro whose name is contained in the string
-.I macro
-until
-.B ..\&
-is encountered.
+.REQ .ami str
+Append to a macro indirectly\[em]its name is in string
+.IR str \[em]until
+encountering
+.RB \[lq] .\|.\& \[rq].
.
.TPx
-.REQ .ami "macro end"
+.REQ .ami "str end-mac-str"
Append to a macro indirectly.
-.I macro
+.
+As
+.request .am ,
+but
+.I str
and
-.I end
-are strings whose contents are interpolated for the macro name and the
-end macro,
+.I end-mac-str
+contain the names of the macro to be appended to,
+and that whose call ends the appendment,
respectively.
.
.TPx
-.REQ .ami1 "macro"
-Same as
-.request .ami
-but with compatibility mode switched off during macro expansion.
+.REQ .ami1 str
+As
+.request .ami ,
+with compatibility mode disabled when the appendment is interpreted.
.
.TPx
-.REQ .ami1 "macro end"
-Same as
-.request .ami
-but with compatibility mode switched off during macro expansion.
+.REQ .ami1 "str end-mac-str"
+As
+.request .ami ,
+with compatibility mode disabled when the appendment is interpreted.
.
+.\" a degenerate case
.TPx
-.REQ .as name
+.REQ .as ident
Create string
-.I name
+.I ident
with empty contents;
no operation if
-.I name
+.I ident
already exists.
.
.TPx
-.REQ .as "name contents"
+.REQ .as "str anything"
Append
-.I contents
+.I anything
to string
-.IR name .
+.IR str .
.
+.\" a doubly degenerate case
.TPx
-.REQ .as1 string
-.TQ
-.REQ .as1 "string contents"
+.REQ .as1 ident
+As
+.RB \[lq] .as
+.IR ident \[rq].
+.
+.TPx
+.REQ .as1 "str anything"
As
.request .as ,
-but with compatibility mode disabled when
-.I contents
-interpolated.
+with compatibility mode disabled when the appendment to string
+.I str
+is interpreted.
.
.TPx
-.REQ .asciify "diversion"
-Unformat ASCII characters, spaces, and some escape sequences in
-.IR diversion .
+.REQ .asciify div
+Unformat ordinary characters,
+spaces,
+and some escape sequences \" XXX: vague
+in diversion
+.IR div .
.
.TPx
.REQ .backtrace
@@ -2621,45 +2638,39 @@ Unset blank line macro (trap).
.
Restore default handling of blank lines.
.
-.
.TPx
-.REQ .blm name
+.REQ .blm mac
Set blank line macro (trap) to
-.IR name .
-.
+.IR mac .
.
.TPx
.REQ .box
Stop directing output to current diversion;
any pending output line is discarded.
.
-.
.TPx
-.REQ .box name
+.REQ .box ident
Direct output to diversion
-.IR name ,
+.IR ident ,
omitting a partially collected line.
.
-.
.TPx
.REQ .boxa
Stop appending output to current diversion;
any pending output line is discarded.
.
-.
.TPx
-.REQ .boxa name
+.REQ .boxa div
Append output to diversion
-.IR name ,
+.IR div ,
omitting a partially collected line.
.
-.
.TPx
.REQ .bp
Break page and start a new one.
.
.TPx
-.REQ .bp "\[+-]N"
+.REQ .bp \[+-]N
Break page,
starting a new one numbered
.IR \[+-]N .
@@ -2683,7 +2694,7 @@ Reset no-break control character to
.dquoted_char \[aq] .
.
.TPx
-.REQ .c2 "o"
+.REQ .c2 o
Recognize ordinary character
.I o
as no-break control character.
@@ -2694,7 +2705,7 @@ Reset control character to
.squoted_char . .
.
.TPx
-.REQ .cc "o"
+.REQ .cc o
Recognize ordinary character
.I o
as the control character.
@@ -2733,44 +2744,40 @@ to characters
.IR c2 ,
and so on.
.
-.
.TPx
-.REQ .ch name
+.REQ .ch mac
Unplant page location trap
-.IR name .
-.
+.IR mac .
.
.TPx
-.REQ .ch "name vpos"
+.REQ .ch "mac vertical-position"
Change page location trap
-.I name
+.I mac
planted by
.request .wh
by moving its location to
-.I vpos
+.I vertical-position
(default scaling unit\~\c
.scaleindicator v ).
.
-.
.TPx
-.REQ .char "c contents"
+.REQ .char "c anything"
Define ordinary or special character
.I c
as
-.IR contents .
+.I anything.
.
.TPx
-.REQ .chop object
+.REQ .chop name
Remove the last character from the macro,
string,
or diversion
-named
-.IR object .
+.I name.
.
.TPx
-.REQ .class "name c1 c2 \fR\&.\|.\|.\&\fP"
+.REQ .class "ident c1 c2 \fR\&.\|.\|.\&\fP"
Define a (character) class
-.I name
+.I ident
comprising the characters or range expressions
.IR c1 ,
.IR c2 ,
@@ -2784,12 +2791,10 @@ making it unavailable for
.request .write
requests.
.
-.
.TPx
.REQ .color
Enable output of color-related device-independent output commands.
.
-.
.TPx
.REQ .color n
If
@@ -2800,7 +2805,6 @@ otherwise,
enable them.
.\" XXX: Should probably interpret negative values as false.
.
-.
.TPx
.REQ .composite "from to"
Map glyph name
@@ -2835,12 +2839,10 @@ ems with em
.IR m .
.\" XXX: m parameter needs more explanation.
.
-.
.TPx
.REQ .cu
Continuously underline the output of the next productive input line.
.
-.
.TPx
.REQ .cu npl
Continuously underline the output of the next
@@ -2851,50 +2853,51 @@ If
.IR npl =0,
stop continuously underlining.
.
-.
.TPx
.REQ .da
Stop appending output to current diversion.
.
-.
.TPx
-.REQ .da name
+.REQ .da div
Append output to diversion
-.IR name .
-.
+.IR div .
.
.TPx
-.REQ .de macro
-Define or redefine
-.I macro
+.REQ .de ident
+Define macro
+.I ident
until
-.RB \[lq] ..\& \[rq]
+.RB \[lq] .\|.\& \[rq]
occurs at the start of a control line in the current conditional block.
.
-.
.TPx
-.REQ .de "macro end"
-Define or redefine
-.I macro
+.REQ .de "ident end-mac"
+Define macro
+.I ident
until
-.I end
-is invoked or called at the start of a control line in the current
-conditional block.
+.I end-mac
+is called at the start of a control line in the current conditional
+block.
.
+.I end-mac
+can be a request.
.
.TPx
-.REQ .de1 "macro"
+.REQ .de1 ident
As
.request .de ,
-but disable compatibility mode during macro expansion.
+with compatibility mode disabled when
+.I mac
+is interpreted.
.
.TPx
-.REQ .de1 "macro end"
+.REQ .de1 "ident end-mac"
As
.RB \[lq] .de
-.IR "macro end" \[rq],
-but disable compatibility mode during macro expansion.
-.
+.IR "ident end-mac" \[rq],
+with compatibility mode disabled when
+.I mac
+is interpreted.
.
.TPx
.REQ .defcolor "ident scheme color-component \f[R].\|.\|."
@@ -2937,46 +2940,44 @@ interpreted using a default scaling unit
which multiplies its value by 65,536
(but clamps it at 65,535).
.
-.
.TPx
-.REQ .dei "macro"
+.REQ .dei str
Define macro indirectly.
.
As
.request .de ,
-but use interpolation of string
-.I macro
-as the name of the defined macro.
-.
+but interpolate string
+.I str
+to obtain the macro's name.
.
.TPx
-.REQ .dei "macro end"
+.REQ .dei "str end-mac-str"
Define macro indirectly.
.
As
.request .de ,
-but use interpolations of strings
-.I macro
+but
+.I str
and
-.I end
-as the names of the defined and end macros.
-.
+.I end-mac-str
+contain the names of the macro to be defined,
+and that whose call ends the definition,
+respectively.
.
.TPx
-.REQ .dei1 "macro"
+.REQ .dei1 str
As
.request .dei ,
-but disable compatibility mode during macro expansion.
-.
+with compatibility mode disabled when the macro is interpreted.
.
.TPx
-.REQ .dei1 "macro end"
+.REQ .dei1 "str end-mac-str"
As
-.request ".dei\~\f[I]macro\~end\f[]" ,
-but disable compatibility mode during macro expansion.
+.request .dei ,
+with compatibility mode disabled when the macro is interpreted.
.
.TPx
-.REQ .device "anything"
+.REQ .device anything
Write
.IR anything ,
read in copy mode,
@@ -2988,7 +2989,7 @@ An initial neutral double quote is stripped to allow
embedding of
leading spaces.
.
.TPx
-.REQ .devicem "name"
+.REQ .devicem name
Write contents of macro or string
.I name
to
@@ -2999,11 +3000,10 @@ output as a device control command.
.REQ .di
Stop directing output to current diversion.
.
-.
.TPx
-.REQ .di name
+.REQ .di ident
Direct output to diversion
-.IR name .
+.IR ident .
.
.TPx
.REQ .do "name \fR\&.\|.\|.\&\fP"
@@ -3024,69 +3024,61 @@ of
is interpreted.
.
.TPx
-.REQ .ds name
-Create empty string
-.IR name .
+.REQ .ds ident
+Create empty string named
+.IR ident .
.
.TPx
-.REQ .ds "name contents"
-Create a string
-.I name
+.REQ .ds "ident anything"
+Create a string named
+.I ident
containing
-.IR contents .
+.IR anything .
.
.TPx
-.REQ .ds1 name
+.REQ .ds1 ident
.TQ
-.REQ .ds1 "name contents"
+.REQ .ds1 "ident anything"
As
.request .ds ,
-but with compatibility mode disabled when
-.I contents
-interpolated.
+with compatibility mode disabled when the string is interpreted.
.
.TPx
.REQ .dt
Clear diversion trap.
.
-.
.TPx
-.REQ .dt "vertical-position name"
+.REQ .dt "vertical-position mac"
Set the diversion trap to macro
-.I name
+.I mac
at
.I vertical-position
(default scaling unit\~\c
.scaleindicator v ).
.
-.
.TPx
.REQ .ec
Recognize
.B \[rs]
as the escape character.
.
-.
.TPx
-.REQ .ec "o"
+.REQ .ec o
Recognize ordinary character
.I o
as the escape character.
.
-.
.TPx
.REQ .ecr
Restore escape character saved with
.request .ecs .
.
-.
.TPx
.REQ .ecs
Save the escape character.
.
-.
.TPx
-.REQ .el "anything"
+.REQ .el anything
Interpret
.I anything
as if it were an input line if the conditional expression of the
@@ -3094,49 +3086,43 @@ corresponding
.request .ie
request was false.
.
-.
.TPx
-.REQ .em name
+.REQ .em mac
Call macro
-.I name
+.I mac
after the end of input.
.
-.
.TPx
.REQ .eo
Disable the escape mechanism in interpretation mode.
.
-.
.TPx
.REQ .ev
Pop environment stack,
returning to previous one.
.
-.
.TPx
-.REQ .ev "env"
+.REQ .ev env
Push current environment onto stack and switch to
-.IR env .
-.
+.IR env ,
+creating it if necessary.
.
.TPx
-.REQ .evc "env"
+.REQ .evc env
Copy environment
.I env
to the current one.
.
-.
.TPx
.REQ .ex
Exit with successful status.
.
-.
.TPx
.REQ .fam
Set default font family to previous value.
.
.TPx
-.REQ .fam "name"
+.REQ .fam name
Set default font family to
.IR name .
.
@@ -3145,36 +3131,35 @@ Set default font family to
Disable field mechanism.
.
.TPx
-.REQ .fc "a"
+.REQ .fc c
Set field delimiter to\~\c
-.I a
+.I c
and pad glyph to space.
.
.TPx
-.REQ .fc "a b"
+.REQ .fc "c1 c2"
Set field delimiter to\~\c
-.I a
+.I c1
and pad glyph to\~\c
-.IR b .
+.IR c2 .
.
.TPx
-.REQ .fchar "c contents"
-Define fallback character (or glyph)
+.REQ .fchar "c anything"
+Define fallback character
+(or glyph)
.I c
as
-.IR contents .
-.
+.IR anything .
.
.TPx
.REQ .fcolor
Restore previous fill color.
.
-.
.TPx
-.REQ .fcolor "c"
-Set fill color to
-.IR c .
-.
+.REQ .fcolor color
+Select
+.I color
+as the fill color.
.
.TPx
.REQ .fi
@@ -3184,7 +3169,6 @@ a pending output line is broken.
Sets
.BR \[rs]n[.u] .
.
-.
.TPx
.REQ .fl
Flush output buffer.
@@ -3193,8 +3177,8 @@ Flush output buffer.
.REQ .fp "pos id"
Mount font with font description file name
.I id
-at non-negative
-.RI position\~ n .
+at non-negative position
+.IR pos .
.
.TPx
.REQ .fp "pos id font-description-file-name"
@@ -3202,8 +3186,8 @@ Mount font with
.I font-description-file-name
as name
.I id
-at non-negative
-.RI position\~ n .
+at non-negative position
+.IR pos .
.
.TPx
.REQ .fschar "f c anything"
@@ -3215,20 +3199,21 @@ as string
.IR anything .
.
.TPx
-.REQ .fspecial "font"
-Reset list of special fonts for
+.REQ .fspecial font
+Empty the list of fonts treated as special when
.I font
-to be empty.
+is selected.
.
.TPx
.REQ .fspecial "font s1 s2 \fR\&.\|.\|.\&\fP"
-When the current font is
-.IR font ,
-then the fonts
+When
+.I font
+is selected,
+treat the fonts
.IR s1 ,
.IR s2 ,
\&.\|.\|.\&
-are special.
+as special.
.
.TPx
.REQ .ft
@@ -3242,11 +3227,10 @@ or
.esc fP .
.
.TPx
-.REQ .ft "font"
+.REQ .ft font
Select typeface
.I font,
-which can be a
-mounting position,
+a mounting position,
abstract style,
or font name;
same as
@@ -3290,12 +3274,11 @@ a multiplier of the current type size in thousandths
.REQ .gcolor
Restore previous stroke color.
.
-.
.TPx
-.REQ .gcolor "c"
-Set stroke color to
-.IR c .
-.
+.REQ .gcolor color
+Select
+.I color
+as the stroke color.
.
.TPx
.REQ .hc
@@ -3304,9 +3287,9 @@ Reset the hyphenation character
(the default).
.
.TPx
-.REQ .hc char
+.REQ .hc c
Change the hyphenation character
-.RI to\~ char .
+.RI to\~ c .
.
.TPx
.REQ .hcode "c1 code1 \fR[\fPc2 code2\fR] .\|.\|.\fP"
@@ -3321,9 +3304,9 @@ to
and so on.
.
.TPx
-.REQ .hla lang
+.REQ .hla ident
Set the hyphenation language to
-.IR lang .
+.IR ident .
.
.TPx
.REQ .hlm n
@@ -3356,27 +3339,23 @@ a hyphen
.RB \[lq] \- \[rq]
indicates a hyphenation point.
.
-.
.TPx
.REQ .hy
Set automatic hyphenation mode to
.BR 1 .
.
-.
.TPx
.REQ .hy\~0
Disable automatic hyphenation;
same as
.BR .nh .
.
-.
.TPx
.REQ .hy mode
Set automatic hyphenation mode to
.IR mode ;
see section \[lq]Hyphenation\[rq] below.
.
-.
.TPx
.REQ .hym
Set the (right) hyphenation margin to
@@ -3408,7 +3387,6 @@ to each inter-word space
(default scaling unit\~\c
.scaleindicator m ).
.
-.
.TPx
.REQ .ie "cond-expr anything"
If
@@ -3421,7 +3399,6 @@ otherwise skip to a corresponding
.request .el
request.
.
-.
.TPx
.REQ .if "cond-expr anything"
If
@@ -3431,7 +3408,6 @@ then interpret
.I anything
as if it were an input line.
.
-.
.TPx
.REQ .ig
Ignore input
@@ -3439,27 +3415,29 @@ Ignore input
.B \[rs]R
on auto-incrementing registers)
until
-.RB \[lq] ..\& \[rq]
+.RB \[lq] .\|.\& \[rq]
occurs at the start of a control line in the current conditional block.
.
-.
.TPx
-.REQ .ig "end"
+.REQ .ig end-mac
Ignore input
(except for side effects of
.B \[rs]R
on auto-incrementing registers)
until
-.BI . end
+.I end-mac
is called at the start of a control line in the current conditional
block.
.
+.I end-mac
+can be a request.
+.
.TPx
.REQ .in
Set indentation amount to previous value.
.
.TPx
-.REQ .in "\[+-]N"
+.REQ .in \[+-]N
Set indentation to
.I \[+-]N
(default scaling unit\~\c
@@ -3470,12 +3448,12 @@ Set indentation to
Cancel any pending input line trap.
.
.TPx
-.REQ .it "npl name"
+.REQ .it "npl mac"
Set
(or replace)
an input line trap in the environment,
-calling macro
-.IR name ,
+calling
+.I mac
after the next
.I npl
productive input lines have been read.
@@ -3489,7 +3467,7 @@ escape sequence are counted separately.
Cancel any pending input line trap.
.
.TPx
-.REQ .itc "npl name"
+.REQ .itc "npl mac"
As
.request .it ,
except that input lines interrupted with the
@@ -3513,7 +3491,7 @@ otherwise enable it.
Unset leader repetition character.
.
.TPx
-.REQ .lc "c"
+.REQ .lc c
Set leader repetition character
.RI to\~ c
(default:
@@ -3527,18 +3505,15 @@ and store the count
in the register
.IR reg .
.
-.
.TPx
.REQ .linetabs
Enable line-tabs mode
(calculate tab positions relative to beginning of output line).
.
-.
.TPx
.REQ .linetabs\~0
Disable line-tabs mode.
.
-.
.TPx
.REQ .lf n
Set number of next input line to
@@ -3571,7 +3546,7 @@ Set line length to previous value.
Does not affect a pending output line.
.
.TPx
-.REQ .ll "\[+-]N"
+.REQ .ll \[+-]N
Set line length to
.I \[+-]N
(default length
@@ -3588,9 +3563,9 @@ Unset the leading space macro (trap).
Restore default handling of lines with leading spaces.
.
.TPx
-.REQ .lsm name
+.REQ .lsm mac
Set the leading space macro (trap) to
-.IR name .
+.IR mac .
.
.TPx
.REQ .ls
@@ -3610,7 +3585,7 @@ blank lines are inserted after each text output line.
Set length of title lines to previous value.
.
.TPx
-.REQ .lt "\[+-]N"
+.REQ .lt \[+-]N
Set length of title lines
(default length
.scalednumber 6.5 i ,
@@ -3646,12 +3621,12 @@ see
.BR .rt .
.
.TPx
-.REQ .mk register
-Mark vertical drawing position in
-.IR register .
+.REQ .mk reg
+Mark vertical drawing position in register
+.IR reg .
.
.TPx
-.REQ .mso "file"
+.REQ .mso file
As
.request .so ,
except that
@@ -3660,21 +3635,18 @@ is sought in the
.I tmac
directories.
.
-.
.TPx
-.REQ .msoquiet "file"
+.REQ .msoquiet file
As
.request .mso ,
but no warning is emitted if
.I file
does not exist.
.
-.
.TPx
.REQ .na
Disable output line adjustment.
.
-.
.TPx
.REQ .ne
Break page if distance to next page location trap is less than one vee.
@@ -3686,7 +3658,6 @@ Break page if distance to next page location trap is less
than distance
(default scaling unit\~\c
.scaleindicator v ).
.
-.
.TPx
.REQ .nf
Disable filling of output lines;
@@ -3695,7 +3666,6 @@ a pending output line is broken.
Clears
.BR \[rs]n[.u] .
.
-.
.TPx
.REQ .nh
Disable automatic hyphenation;
@@ -3748,9 +3718,8 @@ If
cancel suppression.
.\" XXX: negative values accepted; check AT&T troff
.
-.
.TPx
-.REQ .nop "anything"
+.REQ .nop anything
Interpret
.I anything
as if it were an input line.
@@ -3832,9 +3801,9 @@ Output vertical distance that was saved by the
request.
.
.TPx
-.REQ .output contents
+.REQ .output anything
Emit
-.I contents
+.I anything
directly to intermediate output,
allowing leading whitespace if
.I string
@@ -3848,9 +3817,9 @@ Reset page number character to\~\c
.squoted_char % .
.
.TPx
-.REQ .pc "c"
-Page number character.
-.
+.REQ .pc c
+Change the page number character used in titles
+.RI to\~ c .
.
.TPx
.REQ .pev
@@ -3878,7 +3847,7 @@ are suffixed with a tab and asterisk
.RB ( * ).
.
.TPx
-.REQ .pi "program"
+.REQ .pi program
Pipe output to
.I program
.RI ( nroff
@@ -3895,7 +3864,7 @@ The current page length is stored in register
.BR .p .
.
.TPx
-.REQ .pl "\[+-]N"
+.REQ .pl \[+-]N
Change page length to
.I \[+-]N
(default scaling unit\~\c
@@ -3913,9 +3882,8 @@ and
diversions.
.
.TPx
-.REQ .pn "\[+-]N"
-Next page number
-.IR N .
+.REQ .pn \[+-]N
+Set next page number.
.
.TPx
.REQ .pnr
@@ -3930,18 +3898,17 @@ The current page offset is available in register
.BR .o .
.
.TPx
-.REQ .po "\[+-]N"
+.REQ .po \[+-]N
Alter page offset
(default scaling unit\~\c
.scaleindicator m ).
.
.TPx
.REQ .ps
-Return to previous type size.
+Restore previous type size.
.TPx
.
-.
-.REQ .ps "\[+-]N"
+.REQ .ps \[+-]N
Set/increase/decrease the type size to/by
.I N
scaled points
@@ -3962,7 +3929,7 @@ See registers
.BR ury .
.
.TPx
-.REQ .pso "command-line"
+.REQ .pso command-line
Execute
.I command-line
with
@@ -3977,13 +3944,12 @@ disabled by default.
Report names and positions of all page location traps to the standard
error stream.
.
-.
.TPx
.REQ .pvs
Change to previous post-vertical line spacing.
.
.TPx
-.REQ .pvs "\[+-]N"
+.REQ .pvs \[+-]N
Change post-vertical line spacing according to
.I \[+-]N
(default scaling unit\~\c
@@ -4002,17 +3968,19 @@ or
request.
.
.TPx
-.REQ .rd "prompt"
+.REQ .rd prompt
Read insertion.
.
.TPx
.REQ .return
-Return from a macro.
+Stop interpreting an interpolated macro,
+skipping the remainder of its definition.
.
.TPx
-.REQ .return "anything"
-Return twice, namely from the macro at the current level and from the
-macro one level higher.
+.REQ .return anything
+Return twice,
+namely from the macro at the current level and from the macro one level
+higher.
.
.TPx
.REQ .rfschar "f c1 c2 \fR\&.\|.\|.\&\fP"
@@ -4052,7 +4020,10 @@ or string
.
.TPx
.REQ .rn "old new"
-Rename request, macro, diversion, or string
+Rename request,
+macro,
+diversion,
+or string
.I old
to
.IR new .
@@ -4064,13 +4035,11 @@ Rename register
to
.IR reg2 .
.
-.
.TPx
.REQ .rr "reg \f[R].\|.\|."
Remove each register
.IR reg .
.
-.
.TPx
.REQ .rs
Restore spacing;
@@ -4099,25 +4068,22 @@ unit\~\c
.\" XXX: negative values accepted; check AT&T troff
.
.TPx
-.REQ .schar "c contents"
+.REQ .schar "c anything"
Define global fallback character (or glyph)\~\c
.I c
as
-.IR contents .
-.
+.IR anything .
.
.TPx
.REQ .shc
Reset the soft hyphen character to
.esc [hy] .
.
-.
.TPx
.REQ .shc c
Set the soft hyphen character
.RI to\~ c .
.
-.
.TPx
.REQ .shift n
In a macro definition,
@@ -4138,14 +4104,12 @@ Each
is interpreted in units of scaled points (\c
.scaleindicator z ).
.
-.
.TPx
.REQ .so file
Replace the request's control line with the contents of
.IR file ,
\[lq]sourcing\[rq] it.
.
-.
.TPx
.REQ .soquiet file
As
@@ -4154,13 +4118,11 @@ but no warning is emitted if
.I file
does not exist.
.
-.
.TPx
.REQ .sp
Break and move the next text baseline down by one vee,
or until springing a page location trap.
.
-.
.TPx
.REQ .sp dist
Break and move the next text baseline down by
@@ -4189,10 +4151,9 @@ one line height (vee) is added
.I dist
is ignored inside a diversion.
.
-.
.TPx
.REQ .special
-Reset global list of special fonts to be empty.
+Reset global list of fallback special fonts to be empty.
.
.TPx
.REQ .special "s1 s2 \fR\&.\|.\|.\&\fR"
@@ -4306,7 +4267,7 @@ request
.\" XXX: negative values accepted; check AT&T troff
.
.TPx
-.REQ .sy "command-line"
+.REQ .sy command-line
Execute
.I command-line
with
@@ -4370,13 +4331,13 @@ Reserved for internal use.
Unset tab repetition character.
.
.TPx
-.REQ .tc "c"
+.REQ .tc c
Set tab repetition character
.RI to\~ c
(default: none).
.
.TPx
-.REQ .ti "\[+-]N"
+.REQ .ti \[+-]N
Temporarily indent next output line
(default scaling unit\~\c
.scaleindicator m ).
@@ -4387,8 +4348,8 @@ Enable track kerning for
.IR font .
.
.TPx
-.REQ .tl "\f[CB]\[aq]\f[]left\f[CB]\[aq]\f[]center\f[CB]\[aq]\f[]right\
-\f[CB]\[aq]\f[]"
+.REQ .tl \f[CB]\[aq]\f[]left\f[CB]\[aq]\f[]center\f[CB]\[aq]\f[]right\
+\f[CB]\[aq]\f[]
Format three-part title.
.
.TPx
@@ -4414,7 +4375,7 @@ As
without emitting a newline.
.
.TPx
-.REQ .tr "abcd\fR\&.\|.\|.\&\fP"
+.REQ .tr abcd\fR\&.\|.\|.\&\fP
Translate ordinary or special characters
.I a
to
@@ -4436,7 +4397,7 @@ invalid input characters in
are rejected.
.
.TPx
-.REQ .trin "abcd\fR\&.\|.\|.\&\fP"
+.REQ .trin abcd\fR\&.\|.\|.\&\fP
As
.request .tr ,
except that
@@ -4444,7 +4405,7 @@ except that
ignores the translation when a diversion is interpolated.
.
.TPx
-.REQ .trnt "abcd\fR\&.\|.\|.\&\fP"
+.REQ .trnt abcd\fR\&.\|.\|.\&\fP
As
.request .tr ,
except that translations are suppressed in the argument to
@@ -4465,7 +4426,6 @@ Set underline font used by
to
.I font.
.
-.
.TPx
.REQ .ul
Underline
@@ -4474,7 +4434,6 @@ Underline
mode)
the output of the next productive input line.
.
-.
.TPx
.REQ .ul npl
Underline
@@ -4489,46 +4448,40 @@ If
.IR npl =0,
stop underlining.
.
-.
.TPx
-.REQ .unformat "diversion"
-Unformat space characters and tabs in
-.IR diversion ,
+.REQ .unformat div
+Unformat space characters and tabs in diversion
+.IR div ,
preserving font information.
-.
+.\" XXX: too vague
.
.TPx
.REQ .vpt
Enable vertical position traps.
.
-.
.TPx
.REQ .vpt\~0
Disable vertical position traps.
.
-.
.TPx
.REQ .vs
Change to previous vertical spacing.
.
.TPx
-.REQ .vs "\[+-]N"
+.REQ .vs \[+-]N
Set vertical spacing to
.I \[+-]N
(default scaling unit\~\c
.scaleindicator p ).
.
-.
.TPx
.REQ .warn
Enable all warning categories.
.
-.
.TPx
.REQ .warn\~0
Disable all warning categories.
.
-.
.TPx
.REQ .warn n
Enable warnings in categories whose codes sum
@@ -4537,12 +4490,9 @@ Enable warnings in categories whose codes sum
see
.MR @g@troff @MAN1EXT@ .
.
-.
.TPx
-.REQ .warnscale "su"
-Set scaling unit used in certain warnings \" `output_warning()`
-to
-.I su
+.REQ .warnscale scaling-unit
+Select scaling unit used in certain warnings \" `output_warning()`
(one of
.BR u ,
.BR i ,
@@ -4557,26 +4507,23 @@ Ignored in
.B nroff
mode.
.
-.
.TPx
-.REQ .wh vpos
+.REQ .wh vertical-position
Remove visible page location trap at
-.I vpos
+.I vertical-position
(default scaling unit\~\c
.scaleindicator v ).
.
-.
.TPx
-.REQ .wh "vpos name"
+.REQ .wh "vertical-position mac"
Plant macro
-.I name
+.I mac
as page location trap at
-.I vpos
+.I vertical-position
(default scaling unit\~\c
.scaleindicator v ),
removing any visible trap already there.
.
-.
.TPx
.REQ .while "cond-expr anything"
Repeatedly execute
@@ -4585,7 +4532,6 @@ unless and until
.I cond-expr
evaluates false.
.
-.
.TPx
.REQ .write "stream anything"
Write
@@ -7087,7 +7033,7 @@ storing subsequent input lines as the definition.
.
If the optional second argument is not specified,
the definition ends with the control line
-.RB \[lq] .. \[rq]\&
+.RB \[lq] .\|. \[rq]\&
(two dots).
.
Tabs and spaces are permitted between the dots.
@@ -7337,7 +7283,7 @@ is not a true escape sequence,
we can't use
.B \[rs]E
to keep
-.RB \[lq] ..\& \[rq]
+.RB \[lq] .\|.\& \[rq]
from ending a macro definition prematurely.
.
If the multiplicity of backslashes complicates maintenance,
_______________________________________________
Groff-commit mailing list
Groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit
