[groff] 40/46: [docs]: Introduce term: "productive input lines".

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c034004d47f0a7c45a9d09b4f66d1f68d39e92db
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Dec 7 00:07:49 2022 -0600

    [docs]: Introduce term: "productive input lines".
    
    We need this concept to accurately describe the behavior of .ce, .rj,
    and .itc.
    
    * doc/groff.texi (Manipulating Filling and Adjustment): Introduce it
      (with concept index entries) prior to discussion of `ce` and `rj`
      requests.  Document interaction with `\c` escape sequence.  Include
      positive and negative examples of "productive input lines".  Recast
      descriptions of `ce` and `rj` requests to employ the term and
      accurately describe their breaking behavior.
    
      (Input Line Traps): Drop an earlier, less formal, and more awkward
      construct of mine ("lines of input that directly produce written
      output) in favor of new "productive input lines" term.  Point out how
      `it` contrasts with `ce` and `rj` in that "connected" (`\c`-using)
      lines get counted anyway.  Add a somewhat abstract example to
      illustrate concepts.
    
    * man/groff.7.man (Syntax reference conventions): Drop redundant wording
      regarding numeric expressions.  Add "npl" notation to indicate a
      quantity of productive input lines, and introduce the latter concept
      (more tersely than in our Texinfo manual).
    
      (Request short reference) <ce, it, itc, rj>: Sync with our Texinfo
      manual.  Use "npl" notation.  Flag `it` as idiosyncratic (AT&T troff
      compatibility strikes again).
    
      <ce, nn, rj>: Document behavior when argument is 0.
    
      <nn>: Clarify that _output_ lines are numbered.
---
 doc/groff.texi  | 90 +++++++++++++++++++++++++++++++++++++++++------------
 man/groff.7.man | 96 ++++++++++++++++++++++++++++++++++++++++++---------------
 2 files changed, 141 insertions(+), 45 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index f6e81a0dc..a5a6cf35c 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -8085,15 +8085,50 @@ This is an uninteresting sentence.
 @endExample
 @endDefreq
 
+@cindex productive input line
+@cindex input line, productive
+@cindex line, productive input
+To clearly present the next couple of requests, we must introduce the
+concept of ``productive'' input lines.  A @dfn{productive input line} is
+one that directly produces formatted output.  Text lines produce output,
+as do control lines containing requests like @code{tl} or escape
+sequences like @code{\D}.  Macro calls are not themselves productive,
+but their interpolated contents can be; macro calls may therefore be
+@emph{indirectly} productive.  An empty request, and requests and escape
+sequences that define registers or strings or alter the formatting
+environment (such as typeface changes) are @emph{not} productive.  The
+output line continuation escape sequence @code{\c} ``connects'' two
+input lines that would otherwise be counted separately.  @xref{Line
+Continuation}.
+
+@Example
+@c .ll 56n
+.de hello
+Hello, world!
+..
+.ce \" center output of next productive input line
+.
+.nr junk-reg 1
+.ft I
+Chorus: \c
+.ft
+.hello
+Went the day well?
+  @result{}                  @slanted{Chorus:} Hello, world!
+  @result{} Went the day well?
+@endExample
+
 @DefreqList {ce, [@Var{nnn}]}
 @DefregListEndx {.ce}
 @cindex centered text (unfilled)
 @cindex centering lines (@code{ce})
 @cindex lines, centering (@code{ce})
-Center the next @var{nnn} input text lines without filling them.  A
-pending output line is broken.  The count of lines remaining to be
-centered is stored in the read-only register @code{.ce} and is
-associated with the environment (@pxref{Environments}).
+Break (unless the no-break control character is used), center the output
+of the next @var{nnn} productive input lines without filling, then break
+again (regardless of the control character).  The count of lines
+remaining to be centered is stored in the read-only register @code{.ce}
+and is associated with the environment
+(@pxref{Environments}).
 
 @cindex @code{ce} request, difference from @w{@samp{.ad c}}
 While the @w{@samp{.ad c}} request also centers text, it fills the text
@@ -8140,10 +8175,11 @@ argument.
 @cindex justifying text (@code{rj})
 @cindex text, justifying (@code{rj})
 @cindex right-justifying (@code{rj})
-Align the next @var{nnn} input text lines to the right margin without
-filling them.  A pending output line is broken.  The count of lines
-remaining to be right-justified is stored in the read-only register
-@code{.rj} and is associated with the environment
+Break (unless the no-break control character is used), align the output
+of the next @var{nnn} productive input lines to the right margin without
+filling, then break again (regardless of the control character).  The
+count of lines remaining to be centered is stored in the read-only
+register @code{.rj} and is associated with the environment
 (@pxref{Environments}).
 @endDefreq
 
@@ -14469,10 +14505,8 @@ error to invoke @code{dt} in the top-level diversion.
 @cindex input line trap, setting (@code{it})
 @cindex trap, input line, setting (@code{it})
 Set an input line trap, calling macro @var{name} after processing the
-next @var{n}@tie{}lines of input that directly produce written output.
-Only text lines and (some) requests produce output directly.  Macro
-calls of themselves do not---requests or text lines they interpolate
-can.
+next @var{n}@tie{}productive input lines (@pxref{Manipulating Filling
+and Adjustment}).
 
 Consider a macro @samp{.ST @var{s n}} which sets the next
 @var{n}@tie{}input lines in the font style@tie{}@var{s}.
@@ -14499,10 +14533,10 @@ face
 @cindex interrupted lines and input line traps (@code{itc})
 @cindex traps, input line, and interrupted lines (@code{itc})
 @cindex lines, interrupted, and input line traps (@code{itc})
-The @code{itc} request is similar, except that lines interrupted with
-the @code{\c} escape sequence are not applied to the line count.
-@xref{Line Continuation}.  To see the difference, let's change the
-previous example to use @code{itc} instead.
+Unlike the @code{ce} and @code{rj} requests, @code{it} counts lines
+interrupted with the @code{\c} escape sequence separately (@pxref{Line
+Continuation}); @code{itc} does not.  To see the difference, let's
+change the previous example to use @code{itc} instead.
 
 @Example
 @r{@dots{}}
@@ -14512,10 +14546,26 @@ previous example to use @code{itc} instead.
 @r{(second ``face'' oblique)}
 @endExample
 
-Text lines are easily understood as input lines that produce written
-output, but escape sequences like @code{\D}, @code{\l}, and @code{\L},
-do as well; they thus increment the internal line counter tested for
-fulfillment of the input trap line count.  @xref{Drawing Requests}.
+You can think of the @code{ce} and @code{rj} requests as implicitly
+creating an input line trap with @code{itc} that schedules a break when
+the trap is sprung.
+
+@Example
+.de BR
+.  br
+.  @slanted{internal: disable centering-without-filling}
+..
+.
+.de ce
+.  if \\n[.br] .br
+.  itc \\$1 BR
+.  @slanted{internal: enable centering-without-filling}
+..
+@endExample
+
+@need 500
+Let us consider in more detail the sorts of input lines that are or are
+not ``productive''.
 
 @Example
 .de Trap
diff --git a/man/groff.7.man b/man/groff.7.man
index 4334d00b4..9657f2e2b 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2155,7 +2155,24 @@ except when it is read in copy mode.
 .
 .TPx
 .I n
-is a numeric expression that evaluates to an integer value.
+is a numeric expression.
+.
+.TPx
+.I npl
+is a numeric expression constituting a count of subsequent
+.I productive
+input lines;
+that is,
+those that directly produce formatted output.
+.
+Text lines produce output,
+as do control lines containing requests like
+.request .tl
+or escape sequences like
+.esc D .
+.
+Macro calls are not themselves productive,
+but their interpolated contents can be.
 .
 .TPx
 .I N
@@ -2478,13 +2495,21 @@ Set control character to
 .
 .TPx
 .REQ .ce
-Center the next input line.
+Break,
+center the output of the next productive input line without filling,
+and break again.
 .
 .TPx
-.REQ .ce "N"
-Center following
-.I N
-input lines.
+.REQ .ce npl
+Break,
+center the output of the next
+.I npl
+productive input lines without filling,
+then break again.
+.
+If
+.IR npl =0,
+stop centering.
 .
 .TPx
 .REQ .cf "filename"
@@ -3189,23 +3214,26 @@ Set indentation to
 .scaleindicator m ).
 .
 .TPx
-.REQ .it "n name"
+.REQ .it "npl name"
 Set an input trap,
 calling macro
 .IR name ,
 after the next
-.IR n\~ lines
-of input that directly produce formatted output have been read.
+.I npl
+productive input lines have been read.
 .
-.
-.TPx
-.REQ .itc "n name"
-As
-.request .it ,
-but lines interrupted with the
+Lines interrupted with the
 .B \[rs]c
-escape sequence are not applied to the line count.
+escape sequence are counted separately.
 .
+.TPx
+.REQ .itc "npl name"
+Set an input trap,
+calling macro
+.IR name ,
+after the next
+.I npl
+productive input lines have been read.
 .
 .TPx
 .REQ .kern
@@ -3408,15 +3436,20 @@ In line number mode, set number, multiple, spacing, and 
indentation.
 .
 .TPx
 .REQ .nn
-Suppress numbering of the next line to be numbered with
+Suppress numbering of the next output line to be numbered with
 .BR nm .
 .
 .TPx
 .REQ .nn n
-Suppress numbering next
+Suppress numbering of the next
 .I n
-.BR nm -numbered
-lines.
+output lines to be numbered with
+.BR nm .
+.
+If
+.IR n =0,
+cancel suppression.
+.
 .
 .TPx
 .REQ .nop "anything"
@@ -3629,10 +3662,23 @@ Remove the font-specific definitions of glyphs
 .RI font\~ f .
 .
 .TPx
-.REQ .rj "n"
-Right justify the next
-.I n
-input lines.
+.REQ .rj npl
+Break,
+right-align the output of the next productive input line without
+filling,
+then break again.
+.
+.TPx
+.REQ .rj npl
+Break,
+right-align the output of the next
+.I npl
+productive input lines without filling,
+then break again.
+.
+If
+.IR npl =0,
+stop right-aligning.
 .
 .TPx
 .REQ .rm "name"
@@ -6384,7 +6430,7 @@ at a blank line
 .RB ( .blm );
 at a line with leading space characters
 .RB ( .lsm );
-after a certain number of input lines
+after a certain number of productive input lines
 .RB ( .it ,\~ .itc );
 or at the end of input
 .RB ( .em ).