[groff] 01/04: groff(7): Rewrite introduction to escapes.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 2a9c2283c5698cc8346a327d0935f3a3821a79e8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jun 30 23:20:50 2020 +1000

    groff(7): Rewrite introduction to escapes.
    
    Drop usage of page-private macros in the rewritten material.  Retitle
    subsection; "single-character escapes" was wholly inaccurate to describe
    the subsequent content.
---
 man/groff.7.man | 111 +++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 66 insertions(+), 45 deletions(-)

diff --git a/man/groff.7.man b/man/groff.7.man
index 6611620..99c1e33 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2817,66 +2817,87 @@ yet.
 .SH "Escape Sequences"
 .\" ====================================================================
 .
-Escape sequences are in-line language elements usually introduced by a
-backslash
-.squoted_char \[rs]
-and followed by an escape name and sometimes by a required argument.
-.
-Input processing is continued directly after the escaped character or
-the argument (without an intervening separation character).
-.
-So there must be a way to determine the end of the escape name and the
-end of the argument.
+Whereas requests must occur on control lines,
+escape sequences can occur intermixed with text and appear in arguments
+to requests and macros
+(and sometimes other escape sequences).
+.
+An escape sequence
+(or simply \[lq]escape\[rq])
+is introduced by the escape character,
+a backslash
+.RB \[lq] \[rs] \[rq]
+(but see the
+.B .ec
+request).
 .
+The next character identifies the escape's function.
 .
-.P
-This is done by enclosing names (escape name and arguments consisting
-of a variable name) by a pair of brackets
-.BI \[lB] name \[rB]
-and constant arguments (number expressions and characters) by
-apostrophes like
-.BI \[aq] constant \[aq] \f[R].
+Escapes vary in length.
 .
+Some take an argument,
+and of those,
+some have different syntactical forms for a one-character,
+two-character,
+or arbitrary-length argument.
 .
-.P
-There are abbreviations for short names.
+Others accept only an arbitrary-length argument.
 .
-Two-character escape names can be specified by an opening parenthesis
-like
-.esc ( xy
-or
-.esc *( xy
-without a closing counterpart.
+In the former convention,
+a one-character argument follows the function character immediately,
+an opening parenthesis
+.RB \[lq] ( \[rq]
+introduces a two-character argument,
+and an argument of arbitrary length is enclosed in brackets
+.RB \[lq] [] \[rq].
 .
-And all one-character names different from the special characters
-.squoted_char [
-and
-.squoted_char (
-can even be specified without a marker, for example
-.esc n c
+In the latter convention,
+the user selects a delimiter character other than
+.RB \[lq] ( \[rq]
 or
-.esc $ c.
+.RB \[lq] [] \[rq]\[em]the
+neutral apostrophe
+.RB \[lq] \[aq] \[rq]
+is a popular choice and used in this document.
+.
+A few escapes are idiosyncratic,
+and support both of the foregoing conventions
+.RB (\[lq] \[rs]s \[rq]),
+designate their own terminating character
+.RB (\[lq] \[rs]? \[rq]),
+consume input until the next newline
+.RB (\[lq] \[rs]! \[rq],
+.RB \[lq] \[rs]" \[rq],
+.RB \[lq] \[rs]# \[rq]),
+or support an additional modifier character
+.RB (\[lq] \[rs]s \[rq]
+again).
+.
+Once an escape sequence terminates,
+input processing resumes with the next character.
 .
 .
 .P
-Constant arguments of length\~1 can omit the marker apostrophes, too,
-but there is no two-character analogue.
+Escape sequences serve a variety of purposes.
 .
+Widespread uses include
+commenting the source document;
+changing the font style;
+setting the point size;
+interpolating special characters,
+number registers,
+and strings into the text;
+and placement or suppression of break and hyphenation points.
 .
-.P
-While one-character escape sequences are mainly used for in-line
-functions and system-related tasks, the two-letter names following the
-.esc (
-construct are glyphs predefined by the roff system; these are called
-\[oq]Special Characters\[cq] in the classical documentation.
-.
-Escapes sequences of the form
-.esc[] "" name
-denote glyphs too.
+As with requests,
+use of escapes in source documents may interact poorly with a macro
+package you use;
+consult its documentation to learn of \[lq]safe\[rq] escapes or
+alternative facilities it provides to achieve the desired result.
 .
 .
 .\" ====================================================================
-.SS "Single-character escapes"
+.SS "Escape short reference"
 .\" ====================================================================
 .
 .PD 0