gbranden pushed a commit to branch master
in repository groff.
commit 45f22d9d1e4929480deefef7ce8e5138ce96dde9
Author: G. Branden Robinson <[email protected]>
AuthorDate: Sun Jan 25 19:42:40 2026 -0600
[doc,man]: Revise grout "Output Structure" stuff.
---
doc/groff.texi.in | 75 +++++++++++++++++++++++++----------
man/groff_out.5.man | 110 +++++++++++++++++++++++++++++++---------------------
2 files changed, 120 insertions(+), 65 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index f37e63421..3b6c67854 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -23321,12 +23321,18 @@ command.
@node Output Structure
@subsubsection Output Structure
-A correct intermediate output document consists of two parts, the
-@dfn{prologue} and the @dfn{body}.
+Device-independent
+@code{troff} @c system
+output is organized into three parts:@:
+a header,
+a body,
+and a trailer.
-The task of the prologue is to set the general device parameters using
-three exactly specified commands. @command{@g@troff}'s prologue is
-guaranteed to consist of the following three lines (in that order):
+The task of the header is to set general device parameters.
+GNU
+@command{troff} @c GNU
+guarantees that its
+header consists of the following three lines:
@Example
x T @var{device}
@@ -23335,23 +23341,52 @@ x init
@endExample
@noindent
-with the arguments set as outlined in @ref{Device Control Commands}.
+with the parameters
+@var{n},
+@var{h},
+and
+@var{v}
+set as outlined in @ref{Device Control Commands}.
The parser for the device-independent page description language format
is able to interpret additional whitespace and comments as well even in
-the prologue.
-
-The body is the main section for processing the document data.
-Syntactically, it is a sequence of any commands different from the ones
-used in the prologue. Processing is terminated as soon as the first
-@w{@samp{x stop}} command is encountered; the last line of any
-@command{@g@troff} intermediate output always contains such a command.
-
-Semantically, the body is page oriented. A new page is started by a
-@samp{p} command. Positioning, writing, and drawing commands are always
-done within the current page, so they cannot occur before the first
-@samp{p} command. Absolute positioning (by the @samp{H} and @samp{V}
-commands) is done relative to the current page; all other positioning is
-done relative to the current location within this page.
+the header.
+
+The body contains the document's visible content.
+Once an output driver interprets
+@w{@samp{x init}},
+it prepares to handle commands in general.
+Processing terminates when a
+@w{@samp{x stop}}
+command is encountered;
+the last line of any
+GNU
+@command{troff} @c GNU
+page description output always contains such a command.
+
+Semantically,
+the body is page-oriented.
+The @code{p}
+command starts a new page.
+Positioning,
+writing,
+and drawing commands are performed within a page,
+so they cannot occur before the first
+@code{p}
+command.
+The output driver reckons absolute positioning
+(by the
+@code{H}
+and
+@code{V}
+commands)
+with respect to the current page's origin
+at the top left corner,
+and all other positioning relative to the drawing position on the page.
+
+The trailer advances the drawing position to the bottom of the page
+and informs the device that the document
+(or ``job'')
+has ended.
@c ---------------------------------------------------------------------
diff --git a/man/groff_out.5.man b/man/groff_out.5.man
index 6499f068a..d7157b584 100644
--- a/man/groff_out.5.man
+++ b/man/groff_out.5.man
@@ -377,75 +377,95 @@ argument or command.
.SS "Document parts"
.\" ====================================================================
.
-A correct
-.I intermediate output
-document consists of two parts, the
-.I prologue
-and the
-.IR body .
+Device-independent
+.I troff \" system
+output is organized into three parts:
+a header,
+a body,
+and a trailer.
+.
.
.P
-The task of the
-.I prologue
-is to set the general device parameters using three exactly specified
-commands.
+The task of the header is to set general device parameters.
+.
+GNU
+.I troff \" GNU
+guarantees that its
+header consists of the following three lines:
+.
.
-The
-.I groff prologue
-is guaranteed to consist of the following three lines (in that order):
.RS
.P
-.B x\ T
+.B x\~T
.I device
.br
-.B x\ res
-.I n\ h\ v
+.B x\~res
+.I n\~h\~v
.br
.B x init
.RE
-.P
-with the arguments set as outlined in subsection \[lq]Device Control
-Commands\[rq] below.
.
-However, the parser for the
-.I intermediate output
-format is able to swallow additional whitespace and comments as well.
+.
+.P
+with the parameters
+.IR n ,
+.IR h ,
+and
+.I v
+set as outlined in subsection \[lq]Device Control Commands\[rq] below.
+The parser for the device-independent page description language format
+is able to interpret additional whitespace and comments as well even in
+the header.
.
.
.P
-The
-.I body
-is the main section for processing the document data.
+The body contains the document's visible content.
.
-Syntactically, it is a sequence of any commands different from the
-ones used in the
-.IR prologue .
+Once an output driver interprets
+.RB \[lq] "x init" \[rq],
+@w{@samp{x init}},
+it prepares to handle commands in general.
.
-Processing is terminated as soon as the first
-.B x\ stop
-command is encountered; the last line of any
-.I groff intermediate output
-always contains such a command.
+Processing terminates when a
+.RB \[lq] "x stop" \[rq]
+command is encountered;
+the last line of any
+GNU
+.I troff \" GNU
+page description output always contains such a command.
.
.
.P
-Semantically, the
-.I body
-is page oriented.
+Semantically,
+the body is page-oriented.
.
-A new page is started by a
-.BR p \~command.
+The
+.B p
+command starts a new page.
.
-Positioning, writing, and drawing commands are always done within the
-current page, so they cannot occur before the first
-.BR p \~command.
+Positioning,
+writing,
+and drawing commands are performed within a page,
+so they cannot occur before the first
+.B p
+command.
.
-Absolute positioning (by the
+The output driver reckons absolute positioning
+(by the
.B H
and
-.BR V \~commands)
-is done relative to the current page, all other positioning
-is done relative to the current location within this page.
+.B V
+commands)
+with respect to the current page's origin
+at the top left corner,
+and all other positioning relative to the drawing position on the page.
+.
+.
+.P
+The trailer advances the drawing position to the bottom of the page
+and informs the device that the document
+(or \[lq]job\[rq])
+has ended.
.
.
.\" ====================================================================
_______________________________________________
groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
