[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 10/16: groff(7): Fix content nits.
From: |
G. Branden Robinson |
Subject: |
[groff] 10/16: groff(7): Fix content nits. |
Date: |
Mon, 23 Aug 2021 00:06:42 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 6527dca90bc1df5304a347bd9793b884132cea13
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Aug 22 12:56:08 2021 +1000
groff(7): Fix content nits.
* Drop empty "request" and .\" comment line from request list. Neither
of these are requests, syntactically. (I've become accustomed to the
parlance "empty request" for `.`, but perhaps I should retrain myself
to say "empty control line". On the other hand, "empty" can be a
synonym for "null", and a null request name is exactly what is present
on an empty control line.)
* Stop referring to "\." as an escape sequence. We now explain better
why it isn't.
* Clarify that .ab exits with a failure status.
* Clarify that .ex exits with a successful status.
* Revise descriptions of nearly every escape sequence.
---
man/groff.7.man | 555 ++++++++++++++++++++++++++++++++------------------------
1 file changed, 313 insertions(+), 242 deletions(-)
diff --git a/man/groff.7.man b/man/groff.7.man
index 583d50b..17db2ad 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -1282,20 +1282,10 @@ number in parentheses.
.PD 0
.
.TPx
-.REQ .
-Empty line, ignored.
-.
-Useful for structuring documents.
-.
-.TPx
-.REQ .\e\[dq] "anything"
-Complete line is a comment.
-.
-.TPx
.REQ .ab "string"
-Print
+Write
.I string
-on standard error, exit program.
+to the standard error stream and exit with failure status.
.
.
.TPx
@@ -1891,7 +1881,8 @@ to the current one.
.
.TPx
.REQ .ex
-Exit from roff processing.
+Exit with successful status.
+.
.
.TPx
.REQ .fam
@@ -2243,16 +2234,17 @@ and store the count
in the number register
.IR reg .
.
+.
.TPx
.REQ .linetabs
-Enable line-tabs mode (i.e., calculate tab positions relative to output
-line).
+Enable line-tabs mode
+(calculate tab positions relative to beginning of output line).
+.
.
.TPx
.REQ .linetabs\~0
-If
-.I n
-is zero, disable line-tabs mode, otherwise enable it.
+Disable line-tabs mode.
+.
.
.TPx
.REQ .lf "N"
@@ -3232,7 +3224,6 @@ and the following character is processed normally.
.\" ====================================================================
.
The escape sequences
-.esc . ,
.esc \[dq] ,
.esc # ,
.esc $ ,
@@ -3255,13 +3246,15 @@ are interpreted even in copy mode.
.
.TP
.ESC \[dq]
-Start of a comment.
+Comment.
.
Everything up to the end of the line is ignored.
.
.
.TP
.ESC #
+Comment.
+.
Everything up to and including the next newline is ignored.
.
.
@@ -3269,201 +3262,203 @@ Everything up to and including the next newline is
ignored.
.
.TP
.ESC * s
-The string stored in the string variable with one-character name\~\c
-.IR s .
+Interpolate string with one-character
+.RI name\~ s .
+.
.
.TP
.ESC *( st
-The string stored in the string variable with two-character name
-.IR st .
+Interpolate string with two-character
+.RI name\~ st .
+.
.
.TP
.ESC[] * string
-The string stored in the string variable with name
+Interpolate string with name
.I string
-(with arbitrary length).
+(of arbitrary length).
+.
.
.TP
-.ESC[] * "stringvar arg1 arg2 \fR\&.\|.\|.\fP"
-The string stored in the string variable with arbitrarily long name
-.IR stringvar ,
+.ESC[] * "string arg1 arg2 \fR\&.\|.\|.\fP"
+Interpolate string with name
+.I string
+(of arbitrary length),
taking
.IR arg1 ,
.IR arg2 ,
\&.\|.\|.\&
as arguments.
.
+.
.\" ========= macro arguments =========
.
.TP
.ESC $0
-The name by which the current macro was invoked.
+Interpolate name by which currently-executing macro was invoked.
.
-The
-.request .als
-request can make a macro have more than one name.
.
.TP
-.ESC $ x
-Macro or string argument with one-digit number\~\c
-.I x
-in the range 1 to\~9.
+.ESC $ n
+Interpolate macro or string parameter
+.RI numbered\~ n
+.RI (1\|\[<=]\| n \|\[<=]\|9).
+.
.
.TP
-.ESC $( xy
-Macro or string argument with two-digit number
-.I xy
-(larger than zero).
+.ESC $( nn
+Interpolate macro or string parameter
+.RI numbered\~ nn
+.RI (01\|\[<=]\| nn \|\[<=]\|99).
.
.TP
-.ESC[] $ nexp
-Macro or string argument with number
-.IR nexp ,
-where
-.I nexp
-is a numerical expression evaluating to an integer \[>=]1.
+.ESC[] $ nnn
+Interpolate macro or string parameter
+.RI numbered\~ nnn
+.RI ( nnn \|\[>=]\|1).
+.
.
.TP
.ESC $*
-In a macro or string, the concatenation of all the arguments separated
-by spaces.
+Interpolate concatenation of all macro or string parameters,
+separated by spaces.
+.
.
.TP
.ESC $@
-In a macro or string, the concatenation of all the arguments with each
-surrounded by double quotes, and separated by spaces.
+Interpolate concatenation of all macro or string parameters,
+with each surrounded by double quotes and separated by spaces.
+.
.
.TP
.ESC $\[ha]
-In a macro, the representation of all parameters as if they were an
-argument to the
+Interpolate concatenation of all macro or string parameters
+as if they were arguments to the
.request .ds
request.
.
-.\" ========= escaped characters =========
.
-.TP
-.ESC \e
-reduces to a single backslash; useful to delay its interpretation as
-escape character in copy mode.
+.\" ========= escaped characters =========
.
-For a printable backslash, use
-.esc e ,
-or even better
-.esc [rs] ,
-to be independent from the current escape character.
.
.TP
.ESC \[aq]
-The acute accent \[aa]; same as
-.esc (aa .
+Translates to
+.esc [aa] ,
+the acute accent special character.
+.
.
.TP
.ESC \[ga]
-The grave accent \[ga]; same as
-.esc (ga .
+Translates to
+.esc [ga] ,
+the grave accent special character.
+.
.
.TP
.ESC \-
-The \- (minus) sign in the current font.
+Translates to
+.esc [\-] ,
+the minus sign special character.
+.
.
.TP
.ESC _
-The same as
-.esc (ul ,
-the underline character.
+Translates to
+.esc [ul] ,
+the underline special character.
.
-.TP
-.ESC .
-The same as a dot (\[oq].\[cq]).
-Necessary in nested macro definitions so that \[oq]\[rs]\[rs]..\[cq]\&
-expands to \[oq]..\[cq].
.
.TP
.ESC %
-Default hyphenation character.
+Control hyphenation.
+.
.
.TP
.ESC !
-Transparent line indicator.
+Transparent line.
+.
+The remainder of the input line is interpreted
+(1) when the current diversion is read;
+or
+(2) if in the top-level diversion,
+by the output driver.
+.
.
.TP
.ESC? anything
-In a diversion, this transparently embeds
-.I anything
-in the diversion.
-.I anything
-is read in copy mode.
-.
-See also the escape sequences
-.esc !
-and
-.esc ? .
+Transparently embed
+.IR anything ,
+read in copy mode,
+in a diversion.
.
.
.\" ========= spacing [sic; \& and \) don't really space] =========
.
.TP
.ESC \& space
-Unpaddable space size space glyph (no line break).
+Unbreakable,
+non-adjustable word space.
+.
+.
+.TP
+.ESC \[ti]
+Unbreakable,
+adjustable space.
+.
.
.TP
.ESC 0
-Digit-width unbreakable space.
+Unbreakable digit-width space.
+.
.
.TP
.ESC |
-1/6\~em unbreakable (\[lq]thin\[rq]) space glyph;
+Unbreakable 1/6\~em (\[lq]thin\[rq]) space glyph;
zero-width in
.IR nroff .
.
+.
.TP
.ESC \[ha]
-1/12\~em unbreakable (\[lq]hair\[rq]) space glyph;
+Unbreakable 1/12\~em (\[lq]hair\[rq]) space glyph;
zero-width in
.IR nroff .
.
+.
.TP
.ESC &
Non-printing input break.
.
+.
.TP
.ESC )
-Like
-.esc &
-except that it behaves like a glyph declared with the
-.request .cflags
-request to be transparent for the purposes of end-of-sentence
-recognition.
+Non-printing input break,
+transparent to end-of-sentence recognition.
.
.
.TP
.ESC /
Apply italic correction.
.
-Use between an immediately adjacent italic glyph on the left and a roman
-glyph on the right.
+Use between an immediately adjacent oblique glyph on the left and an
+upright glyph on the right.
.
.
.TP
.ESC ,
Apply left italic correction.
.
-Use between an immediately adjacent roman glyph on the left and an
-italic glyph on the right.
-.
+Use between an immediately adjacent upright glyph on the left and an
+oblique glyph on the right.
.
-.TP
-.ESC \[ti]
-Unbreakable space that stretches like a normal inter-word space when a
-line is adjusted.
.
.TP
.ESC :
-Insert a non-printing break point
+Non-printing break point
(similar to
-.esc %
-but without a soft hyphen character).
+.esc % ,
+but never produces a hyphen glyph).
.
.
.TP
@@ -3484,47 +3479,65 @@ End conditional input.
.\" ========= longer escape names =========
.
.TP
-.ESC ( sc
-A glyph with two-character name
-.IR sc ;
-see section \[lq]Special Characters\[rq] below.
+.ESC ( gl
+Interpolate glyph with two-character name
+.IR gl .
+.
.
.TP
-.ESC[] "" name
-A glyph with name
-.I name
+.ESC[] "" glyph
+Interpolate glyph with name
+.I glyph
(of arbitrary length).
.
+.
.TP
-.ESC[] "" "comp1 comp2 \fR\&.\|.\|.\&\fP"
-A composite glyph with components
+.ESC[] "" "base-glyph comp1 comp2 \fR\&.\|.\|."
+Interpolate composite glyph constructed from
+.I base-glyph
+and components
.IR comp1 ,
.IR comp2 ,
-\&.\|.\|.
+and so on.
+.
.
.\" ========= alphabetical escapes =========
.
.TP
.ESC a
-Non-interpreted leader character.
+In copy mode,
+interpolate leader character.
+.
.
.TP
.ESCq A anything
-If
+Interpolate 1 if
.I anything
-is acceptable as a name of a string, macro, diversion, register,
-environment or font it expands to\~1, and to\~0 otherwise.
+is an acceptable identifier for a string,
+macro,
+diversion,
+register,
+environment,
+or font,
+and\~0 otherwise.
+.
.
.TP
.ESCq b abc\fR\&.\|.\|.\&\fP
-Bracket building function.
+Build bracket:
+stack glyphs
+.IR a ,
+.IR b ,
+.IR c .\|.\|.\&
+vertically.
+.
.
.TP
.ESCq B anything
-If
+Interpolate 1 if
.I anything
-is acceptable as a valid numeric expression it expands to\~1, and
-to\~0 otherwise.
+is a valid numeric expression,
+and\~0 otherwise.
.
.
.TP
@@ -3534,11 +3547,11 @@ Continue output line at next input line.
.
.TP
.ESCq C glyph
-The glyph called
-.IR glyph ;
-same as
+As
.esc[] "" glyph ,
-but compatible to other roff versions.
+but compatible with other
+.I troff \" generic
+implementations.
.
.
.TP
@@ -3549,73 +3562,87 @@ Move downward \[12]\~vee
.
.
.TP
-.ESCq D charseq
-Draw a graphical element defined by the characters in
-.IR charseq ;
-see the
-.I groff
-Texinfo manual for details.
+.ESCq D anything
+Send
+.I anything
+to the output device as a drawing command;
+see
+.IR groff_out (@MAN5EXT@).
+.
.
.TP
.ESC e
-Interpolate current escape character.
+Interpolate escape character.
+.
.
.TP
.ESC E
-Equivalent to an escape character, but is not interpreted in copy mode.
+As
+.esc e ,
+but not interpreted in copy mode.
+.
.
.TP
.ESC f F
-Change to font with one-character name or one-digit number\~\c
-.IR F .
+Change to font or style with one-character name or one-digit
+.RI position\~ F .
+.
.
.TP
.ESC fP
-Switch back to previous font.
+Switch to previous font or style.
+.
.
.TP
-.ESC f( fo
-Change to font with two-character name or two-digit number
-.IR fo .
+.ESC f( ft
+Change to font with two-character name or two-digit
+.RI position\~ ft .
+.
.
.TP
.ESC[] f font
-Change to font with arbitrarily long name or number expression
+Change to font with arbitrarily long name or position
.IR font .
.
+.
.TP
.ESC[] f ""
-Switch back to previous font.
+Switch to previous font or style.
+.
.
.TP
.ESC F f
-Change to font family with one-character name\~\c
-.IR f .
+Change to font family with one-character
+.RI name\~ f .
+.
.
.TP
.ESC F( fm
-Change to font family with two-character name
-.IR fm .
+Change to font family with two-character
+.RI name\~ fm .
+.
.
.TP
.ESC[] F fam
Change to font family with arbitrarily long name
.IR fam .
.
+.
.TP
.ESC[] F ""
-Switch back to previous font family.
+Switch to previous font family.
.
.
.TP
.ESC g r
-Interpolate format of register with one-character name\~\c
-.IR r .
+Interpolate format of register with one-character
+.RI name\~ r .
.
.
.TP
.ESC g( rg
-Interpolate format of register with two-character name
+Interpolate format of register with two-character
+.RI name\~ rg .
.IR rg .
.
.
@@ -3627,110 +3654,125 @@ Interpolate format of register with arbitrarily long
name
.
.TP
.ESCq h N
-Local horizontal motion; move right
-.I N
+Horizontally move
+.IR N \~ens
+(or specified units)
+right
(left if negative).
.
+.
.TP
.ESCq H N
Set height of current font to
-.IR N .
+.IR N \~scaled points
+(or specified units).
+.
.
.TP
.ESC k r
-Mark horizontal position in one-character
-.RI register\~ r .
+Mark horizontal position in one-character register
+.RI name\~ r .
.
.TP
.ESC k( rg
-Mark horizontal position in two-character
-.RI register\~ rg .
+Mark horizontal position in two-character register
+.RI name\~ rg .
+.
.
.TP
.ESC[] k reg
Mark horizontal position in register with arbitrarily long
.RI name\~ reg .
.
+.
.TP
-.ESCq l N\f[R][\f[]c\f[R]]
-Horizontal line drawing function (optionally using character
-.IR c ).
+.ESCq l N\f[R][\f[]g\f[R]]
+Draw horizontal line of length
+.IR N \~ems
+(or specified units),
+optionally using
+.RI glyph\~ g .
+.
.
.TP
-.ESCq L N\f[R][\f[]c\f[R]]
-Vertical line drawing function (optionally using character
-.IR c ).
+.ESCq L N\f[R][\f[]g\f[R]]
+Draw vertical line of length
+.IR N \~vees
+(or specified units),
+optionally using
+.RI glyph\~ g .
+.
.
.TP
.ESC m c
-Change to color with one-character name\~\c
-.IR c .
+Change drawing color to that with one-character
+.RI name\~ c .
+.
.
.TP
.ESC m( cl
-Change to color with two-character name
-.IR cl .
+Change drawing color to that with two-character
+.RI name\~ cl .
+.
.
.TP
.ESC[] m color
-Change to color with arbitrarily long name
-.IR color .
+Change drawing color to that with arbitrarily long
+.RI name\~ color .
+.
.
.TP
.ESC[] m ""
-Switch back to previous color.
+Switch to previous drawing color.
+.
.
.TP
.ESC M c
-Change filling color for closed drawn objects to color with
-one-character name\~\c
-.IR c .
+Change fill color to that with one-character
+.RI name\~ c .
+.
.
.TP
.ESC M( cl
-Change filling color for closed drawn objects to color with
-two-character name
-.IR cl .
+Change fill color to that with two-character
+.RI name\~ cl .
+.
.
.TP
.ESC[] M color
-Change filling color for closed drawn objects to color with
-arbitrarily long name
-.IR color .
+Change fill color to that with arbitrarily long
+.RI name\~ color .
+.
.
.TP
.ESC[] M ""
Switch to previous fill color.
.
+.
.TP
.ESC n r
-The numerical value stored in the register variable with the
-one-character name\~\c
-.IR r .
+Interpolate value stored in register with one-character
+.RI name\~ r .
+.
.
.TP
-.ESC n( re
-The numerical value stored in the register variable with the
-two-character name
-.IR re .
+.ESC n( rg
+Interpolate value stored in register with two-character
+.RI name\~ rg .
+.
.
.TP
.ESC[] n reg
-The numerical value stored in the register variable with arbitrarily
-long name
-.IR reg .
+Interpolate value stored in register with arbitrarily long
+.RI name\~ reg .
+.
.
.TP
.ESCq N n
-Typeset the glyph with index\~\c
-.I n
+Interpolate glyph with
+.RI index\~ n
in the current font.
.
-No special fonts are searched.
-.
-Useful for adding (named) entities to a document using the
-.request .char
-request and friends.
.
.TP
.ESCq o abc\fR\&.\|.\|.\&\fP
@@ -3738,7 +3780,8 @@ Overstrike glyphs
.IR a ,
.IR b ,
.IR c ,
-etc.
+and so on.
+.
.
.TP
.ESC O0
@@ -3766,11 +3809,13 @@ Move \[lq]in reverse\[rq] (upward) 1\~vee
.
.
.TP
-.ESCq R "name\~\[+-]n"
-The same as
-.request .nr
+.ESCq R "name\~\[+-]N"
+Set,
+increment,
+or decrement register
.I name
-.IR \[+-]n .
+.RI by\~ N .
+.
.
.TP
.ESC s \[+-]N
@@ -3788,10 +3833,11 @@ a non-zero
must be in the range 4\[en]39.)
.
Otherwise,
-same as
+as
.request .ps
request.
.
+.
.TP
.ESC s( \[+-]N
.TQ
@@ -3804,10 +3850,11 @@ scaled points;
.I N
is a two-digit number \[>=]1.
.
-Same as
+As
.request .ps
request.
.
+.
.TP
.ESC[] s \[+-]N
.TQ
@@ -3824,19 +3871,23 @@ Set/increase/decrease the point size to/by
.I N
scaled points.
.
-Same as
+As
.request .ps
request.
.
+.
.TP
.ESCq S N
-Slant output by
+Slant output glyphs by
.I N
-degrees.
+degrees;
+the direction of text flow is positive.
+.
.
.TP
.ESC t
-Non-interpreted horizontal tab.
+In copy mode,
+interpolate tab character.
.
.
.TP
@@ -3848,64 +3899,84 @@ Move upward \[12]\~vee
.
.TP
.ESCq v N
-Local vertical motion; move down
-.I N
+Vertically move
+.IR N \~vees
+(or specified units)
+down
(up if negative).
.
+.
.TP
.ESC V e
-The contents of the environment variable with one-character
-name\~\c
-.IR e .
+Interpolate contents of environment variable with one-character
+.RI name\~ e .
+.
.
.TP
.ESC V( ev
-The contents of the environment variable with two-character name
-.IR ev .
+Interpolate contents of environment variable with two-character
+.RI name\~ ev .
+.
.
.TP
.ESC[] V env
-The contents of the environment variable with arbitrarily long name
-.IR env .
+Interpolate contents of environment variable with arbitrarily long
+.RI name\~ env .
+.
.
.TP
-.ESCq w string
-The width of the glyph sequence
-.IR string .
+.ESCq w anything
+Interpolate width of
+.IR anything ,
+formatted in a dummy environment.
+.
.
.TP
.ESCq x N
-Extra line-space function (negative before, positive after).
+Increase required line space by
+.IR N \~vees
+(or specified units;
+negative before,
+positive after).
+.
.
.TP
-.ESCq X string
-Output
-.I string
-as device control function.
+.ESCq X anything
+Send
+.I anything
+to the output device as a control command;
+see
+.IR groff_out (@MAN5EXT@).
+.
.
.TP
.ESC Y n
-Output string variable or macro with one-character name\~\c
-.I n
-uninterpreted as device control function.
+Send interpolation of string or macro with one-character
+.RI name\~ n
+to the output device as a control command.
+.
.
.TP
.ESC Y( nm
-Output string variable or macro with two-character name
-.I nm
-uninterpreted as device control function.
+Send interpolation of string or macro with two-character
+.RI name\~ nm
+to the output device as a control command.
+.
.
.TP
.ESC[] Y name
-Output string variable or macro with arbitrarily long name
-.I name
-uninterpreted as device control function.
+Send interpolation of string or macro with arbitrarily long
+.RI name\~ name
+to the output device as a control command.
+.
.
.TP
.ESC z c
-Print
+Output glyph
.I c
-with zero width (without spacing).
+without advancing the print position,
+as if it were zero-width.
+.
.
.TP
.ESCq Z anything
@@ -3913,7 +3984,7 @@ Print
.I anything
and then restore the horizontal and vertical position;
.I anything
-may not contain tabs or leaders.
+must not contain tabs or leaders.
.
.PD
.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 10/16: groff(7): Fix content nits.,
G. Branden Robinson <=