gbranden pushed a commit to branch master
in repository groff.
commit 56aa02a437b375412ad014b8a97ffc3d3a3d223e
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun Mar 15 07:40:44 2026 -0500
[doc,man]: Expand "productive input lines" stuff.
Also break Texinfo input lines in a roff-friendly way.
---
doc/groff.texi.in | 54 +++++++++++++++++++++++++++++++-----------
man/groff.7.man | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++--
man/groff_diff.7.man | 59 ++++++++++++++++++++++++++++++++++++++++++++-
3 files changed, 163 insertions(+), 17 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 32f35cb2b..2d0e87748 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -9739,28 +9739,54 @@ This is an uninteresting sentence.
@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.
+To clearly present the next couple of requests,
+we must introduce the concept of ``productive'' input lines.
+A
+@dfn{productive input line}
+directly produces formatted output.
Text lines produce output,@footnote{though not necessarily to the output
device;
see
@ref{Diversions}}
as do control lines containing requests like
@samp{.tl //Page %//}
-or escape sequences like
-@samp{\l'1i'}.
+or an escape sequence like
+@samp{\l'1i'}
+(when not itself nested inside a
+@code{\w}
+escape sequence).
+Register,
+string,
+and macro definitions are not productive;
+neither are
+empty requests,
+nor requests and escape sequences that alter the formatting environment
+(as with changes to the size,
+face,
+height,
+slant,
+or color of the type).
Macro calls are not themselves productive,
but their interpolations can be.
-Empty requests, and requests and escape sequences that define
-registers or strings or alter the formatting environment (as with
-changes to the size, face, height, slant, or color of the type) are not
-productive.@footnote{If you're not sure whether an input line has been
-productive, you can use the @code{pline} request before and after it to
-see whether it produced any output nodes. @xref{Debugging}.} We will
-also preview the output line continuation escape sequence, @code{\c},
-which ``connects'' two input lines that would otherwise be counted
-separately. @footnote{@xref{Line Continuation}.}
+In
+GNU
+@command{troff}, @c GNU
+if an input line by itself formats an output document,
+it is productive;
+otherwise not.@footnote{This test does not work with AT&T
+@command{troff}, @c AT&T
+which generates device-independent output
+even when it does not need to.}
+You can also use the
+@code{pline}
+request before and after an input line
+to see whether it produced any (additional) output
+nodes.@footnote{@xref{Debugging}.}
+
+We also preview the output line continuation escape sequence,
+@code{\c},
+which ``connects'' two input lines
+that would otherwise be counted separately.@footnote{@xref{Line Continuation}.}
@Example
@c .ll 56n
diff --git a/man/groff.7.man b/man/groff.7.man
index 71c6b565e..ed7aa3a0d 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -2500,6 +2500,62 @@ escape sequences do.
.
.
.\" ====================================================================
+.SH "Productive input lines"
+.\" ====================================================================
+.
+To clearly describe some requests,
+.I groff
+requires the concept of \[lq]productive input lines\[rq].
+.
+A
+.I "productive input line"
+directly produces formatted output.
+.
+Text lines produce output,
+as do control lines containing requests such as
+.B tl
+or an escape sequence like
+.B \[rs]l
+(when not itself nested inside a
+.B \[rs]w
+escape sequence).
+.
+Register,
+string,
+and macro definitions are not productive;
+neither are
+empty requests,
+nor requests and escape sequences that alter the formatting environment
+(as with changes to the size,
+face,
+height,
+slant,
+or color of the type).
+.
+Macro calls are not themselves productive,
+but their interpolations can be.
+.
+In
+GNU
+.I troff, \" GNU
+if an input line by itself formats an output document,
+it is productive;
+otherwise not.
+.
+(This test does not work with
+AT&T
+.I troff, \" AT&T
+which generates device-independent output
+even when it does not need to.)
+.
+You can also use the
+.B pline
+request before and after an input line
+to see whether it produced any (additional) output nodes;
+see section \[lq]Debugging\[rq] below.
+.
+.
+.\" ====================================================================
.SH "Syntax reference conventions"
.\" ====================================================================
.
@@ -2684,8 +2740,15 @@ those that directly produce formatted output.
Text lines produce output,
as do control lines containing requests like
.RB \[lq] ".tl //\^Page %//\^" \[rq]
-or escape sequences like
-.RB \[lq] \[rs]\^l\[aq]1i\[aq] \[rq].
+or an escape sequence like
+.RB \[lq] \[rs]\^l\[aq]1i\[aq] \[rq]
+(when not itself nested within a
+.B \[rs]w
+escape sequence).
+.
+Register,
+string,
+and macro definitions are not productive.
.
Macro calls are not themselves productive,
but their interpolations can be.
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index bfa76526d..46aef7a3f 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -757,7 +757,7 @@ set with another new drawing command.
.
.
.\" ====================================================================
-.SS "Notational conventions"
+.SS "Notation and terminology"
.\" ====================================================================
.
In the request and escape sequence descriptions below,
@@ -805,6 +805,63 @@ fully interprets,
in contrast to copy mode.
.
.
+.P
+GNU
+.I troff \" GNU
+documentation refers to \[lq]productive input lines\[rq],
+a distinction recognized by the
+AT&T
+.I troff \" AT&T
+formatter but which had no name.
+.
+A
+.I "productive input line"
+directly produces formatted output.
+.
+Text lines produce output,
+as do control lines containing requests such as
+.B tl
+or an escape sequence like
+.B \[rs]l
+(when not itself nested inside a
+.B \[rs]w
+escape sequence).
+.
+Register,
+string,
+and macro definitions are not productive;
+neither are
+empty requests,
+nor requests and escape sequences that alter the formatting environment
+(as with changes to the size,
+face,
+height,
+slant,
+or color of the type).
+.
+Macro calls are not themselves productive,
+but their interpolations can be.
+.
+In
+GNU
+.I troff, \" GNU
+if an input line by itself formats an output document,
+it is productive;
+otherwise not.
+.
+(This test does not work with
+AT&T
+.I troff, \" AT&T
+which generates device-independent output
+even when it does not need to.)
+.
+You can also use the
+.B pline
+request before and after an input line
+to see whether it produced any (additional) output nodes;
+see section \[lq]Debugging\[rq] below.
+.
+.
.\" ====================================================================
.SS "Escape sequences"
.\" ====================================================================
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
