[groff] 03/09: [docs]: Document .lf more accurately.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 69c9bc88974ae7dfddd7b90afd35575816a14948
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Nov 29 00:00:31 2020 +1100

    [docs]: Document .lf more accurately.
    
    * doc/groff.texi (Debugging): Describe its actual use case more clearly.
    
    * doc/groff.texi (Implementation Differences):
    * man/groff_diff.7.man (Implementation Differences):
      + Document behavioral difference from AT&T troff .lf here.
---
 doc/groff.texi       | 27 ++++++++++++++-------------
 man/groff_diff.7.man | 16 ++++++++++++++++
 2 files changed, 30 insertions(+), 13 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index b3a4e17..4903c96 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -14820,19 +14820,16 @@ standard error stream.
 @cindex setting input line number (@code{lf})
 @cindex input line number, setting (@code{lf})
 @cindex number, input line, setting (@code{lf})
-Change the line number and optionally the file name @code{gtroff} shall
-use for error and warning messages.  @var{line} is the input line number
-of the @emph{next} line.
-
-Without argument, the request is ignored.
-
-This is a debugging aid for documents that are split into many files,
-then put together with @code{soelim} and other preprocessors.  Usually,
-it isn't invoked manually.
+Change the line number and optionally the file name GNU @code{troff}
+shall use for error and warning messages.  @var{line} is the input line
+number of the @emph{next} line.  Without an argument, the request is
+ignored.
 
-@acronym{AT&T} @code{troff} and other implementations handle @code{lf}
-differently.  For them, @var{line} changes the line number of the
-@emph{current} line.
+This request is primarily a debugging aid for documents that undergo
+preprocessing.  Programs like @command{tbl} that transform input in
+their own languages to @code{roff} requests use it so that any
+diagnostic messages emitted by @code{troff} correspond to the original
+source document.
 @endDefreq
 
 @DefreqList {tm, string}
@@ -15321,9 +15318,13 @@ at the beginning of your file, followed by
 at the end.  As in the C language, we all have to share one big
 name space, so choose a register name that is unlikely to collide with
 other uses.
-
 @endDefreq
 
+@cindex @code{lf} request, incompatibilities with @acronym{AT&T} @code{troff}
+@acronym{AT&T} @code{troff} and other implementations handle the
+@code{lf} request differently.  For them, its @var{line} argument
+changes the line number of the @emph{current} line.
+
 @cindex input level in delimited arguments
 @cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff}
 Normally, GNU @code{troff} preserves the input level in delimited
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index babe863..d316f94 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -4760,6 +4760,22 @@ As in the C language,
 we all have to share one big name space,
 so choose a register name that is unlikely to collide with other uses.
 .
+.
+.P
+AT&T
+.I troff
+and other implementations handle
+.B .lf
+differently.
+.
+For them,
+its
+.I line
+argument changes the line number of the
+.I current
+line.
+.
+.
 .P
 Normally,
 .I groff