[groff] 08/18: [docs]: Update line continuation discussion.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c89522d4a622f55ed2fc4bafc7c30d6cbb087484
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Aug 17 07:01:31 2021 +1000

    [docs]: Update line continuation discussion.
---
 doc/groff.texi  | 29 ++++++++++++---------
 man/groff.7.man | 81 ++++++++++++++++++++++++++++++++++++++++++++-------------
 2 files changed, 80 insertions(+), 30 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 2ccda43..6cc3617 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -9060,9 +9060,9 @@ continuation; the latter is also called 
@dfn{interrupting} a line.
 @DefescList {\\@key{RET}, , ,}
 @DefescItemx {\\c, , ,}
 @DefregListEndx {.int}
-Continue a line.  @code{\@key{RET}} (this is a backslash at the end of a
-line immediately followed by a newline) works on the input level,
-suppressing the effects of the following newline in the input.
+Continue an input line.  @code{\@key{RET}} (this is a backslash at the
+end of a line immediately followed by a newline) suppresses the effects
+of the following newline in the input.
 
 @Example
 This is a \
@@ -9073,11 +9073,10 @@ This is a \
 The @samp{|} operator is also affected.
 
 @cindex @code{\R}, after @code{\c}
-@code{\c} works on the output level.  Anything after this escape on the
-same line is ignored except @code{\R}, which works as usual.  Anything
-before @code{\c} on the same line is appended to the pending output
-line.  The next non-command line after an interrupted line counts as a
-new input line.
+Continue an output line.  Anything on the input line after @code{\c} is
+ignored except @code{\R}, which works as usual.  In contrast to
+@code{\@key{RET}}, a line after @code{\c} is treated as an input line,
+so a control character is recognized at its beginning.
 
 The visual results depend on whether filling is enabled;
 @xref{Manipulating Filling and Adjustment}.
@@ -9111,13 +9110,19 @@ test.
 @endExample
 @end itemize
 
-An intervening control line that causes a break is stronger than
-@code{\c}, flushing out the pending output line in the usual way.
+An intervening control line that causes a break overrides @code{\c},
+flushing out the pending output line in the usual way.
 
 @cindex interrupted line register (@code{.int})
+@cindex continued output line register (@code{.int})
 The @code{.int} register contains a positive value if the last output
-line was interrupted with @code{\c}; this is associated with the
-environment (@pxref{Environments}).
+line was continued with @code{\c}; this datum is associated with the
+environment (@pxref{Environments}).@footnote{Historically, the @code{\c}
+escape sequence has proven challenging to characterize.  Some sources
+say it ``connects the next input text'' (to the input line on which it
+appears); others describe it as ``interrupting'' text, on the grounds
+that a text line is interrupted without breaking, perhaps to inject a
+request invocation or macro call.}
 @endDefesc
 
 
diff --git a/man/groff.7.man b/man/groff.7.man
index 6862e42..ad5a5f9 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -676,7 +676,7 @@ use the escape sequences
 .esc \[ha] ,
 or
 .esc h ;
-see section \[lq]Escape Sequences\[rq] below.
+see section \[lq]Escape sequences\[rq] below.
 .
 An adjustable but non-breaking space is available with
 .esc \[ti] .
@@ -687,13 +687,7 @@ In text,
 a newline puts an inter-word space onto the output and triggers
 end-of-sentence recognition on the preceding text.
 .
-.esc c
-at the end of an input line suppresses these functions.
-.
-Continuation lines can be specified by an escaped newline, i.e., by
-specifying a backslash
-.squoted_char \[rs]
-as the last character of a line.
+See section \[lq]Line continuation\[rq] below.
 .
 .IP \f[CI]tab\f[]
 If a tab character occurs during text the interpreter makes a
@@ -703,6 +697,63 @@ There is a sophisticated interface for handling tab 
positions.
 .
 .
 .\" ====================================================================
+.SH "Line continuation"
+.\" ====================================================================
+.
+A backslash
+.B \[rs]
+at the end of a line immediately followed by a newline suppresses the
+effects of that newline on the input.
+.
+The next input line thus retains the classification of its predecessor
+as a control or text line.
+.
+The
+.esc c
+escape sequence continues an output line.
+.
+Anything on the input line after
+.esc c
+is ignored except
+.esc R ,
+which works as usual.
+.
+In contrast to
+.BI \[rs] newline\c
+,
+a line after
+.esc c
+is treated as an input line,
+so a control character is recognized at its beginning.
+.
+The visual results depend on whether filling is enabled.
+.
+An intervening control line that causes a break overrides
+.esc c ,
+flushing out the pending output line in the usual way.
+.
+The
+.register .int
+contains a positive value if the last output line was continued with
+.esc c ;
+this datum is associated with the
+environment.
+.
+.
+.P
+Historically,
+the
+.esc c
+escape sequence has proven challenging to characterize.
+.
+Some sources say it \[lq]connects the next input text\[rq]
+(to the input line on which it appears);
+others describe it as \[lq]interrupting\[rq] text,
+on the grounds that a text line is interrupted without breaking,
+perhaps to inject a request invocation or macro call.
+.
+.
+.\" ====================================================================
 .SH "Numerical expressions"
 .\" ====================================================================
 .
@@ -3413,7 +3464,8 @@ but without a soft hyphen character).
 .
 .TP
 .ESC "" newline
-Ignored newline, for continuation lines.
+Continue current input line on the next.
+.
 .
 .\" ========= structuring =========
 .
@@ -3470,18 +3522,11 @@ If
 is acceptable as a valid numeric expression it expands to\~1, and
 to\~0 otherwise.
 .
+.
 .TP
 .ESC c
 Continue output line at next input line.
-Anything after this escape on the same line is ignored except
-.ESC R
-(which works as usual).
-Anything before
-.ESC c
-on the same line is appended to the current partial output line.
-The next non-command line after a line interrupted with
-.ESC c
-counts as a new input line.
+.
 .
 .TP
 .ESCq C glyph