gbranden pushed a commit to branch master
in repository groff.
commit 1cadb8b45c0e70ba028ce87d3302159189f0cb2d
Author: G. Branden Robinson <[email protected]>
AuthorDate: Wed Aug 16 06:12:15 2023 -0500
[docs]: Revise discussion of paper format.
* PROBLEMS:
* doc/groff.texi:
* src/roff/groff/groff.1.man: Do it.
---
PROBLEMS | 53 ++++++++++++--------
doc/groff.texi | 58 +++++++++++-----------
src/roff/groff/groff.1.man | 119 ++++++++++++++++++++++++---------------------
3 files changed, 126 insertions(+), 104 deletions(-)
diff --git a/PROBLEMS b/PROBLEMS
index ffddba8d7..bbebaf3ee 100644
--- a/PROBLEMS
+++ b/PROBLEMS
@@ -568,33 +568,46 @@ available in the devps directory.
* I've configured groff for A4 paper, but GNU troff still seems to think
that the length of a page (interpolated by `\n(.p`) is 11 inches.
-This is intentional. The PAGE option recognized during configuration
-populates the device description files for the output drivers grodvi(1),
-groplbp(1), grolj4(1), gropdf(1), and grops(1) with groff's new
-"papersize" directive. If this directive is not present, the formatter
-assumes a page length of 11 inches for compatibility with AT&T troff.
-
-The page length can be changed with the `pl` request, but macro packages
-often do not support alteration of the paper format within a document.
-One might, for instance, want to switch between portrait and landscape
-orientations. Packages do not take a consistent approach to
+The "configure" script recognizes a PAGE parameter. Set it like this.
+
+ $ ./configure PAGE=A4
+
+If the parameter is not set, the script undertakes a variety of efforts
+to figure out the correct default paper format, such as checking an
+"/etc/papersize" file. If it determines the paper format through such
+inference, the source of information is reported in the Autoconf
+"checking default paper format" message.
+
+This paper format populates the device description files for the output
+drivers grodvi(1), groplbp(1), grolj4(1), gropdf(1), and grops(1) with a
+"papersize" directive. (See groff_font(5).) If this directive is not
+present, the formatter and output drivers assume a page length of 11
+inches for compatibility with AT&T troff.
+
+In the formatter, the `pl` request changes the page length, but macro
+packages often do not support alteration of the paper format within a
+document. One might, for instance, want to switch between portrait and
+landscape orientations. Macro packages lack a consistent approach to
configuration of parameters dependent on the paper format; some, like
"ms", benefit from a preamble in the document prior to the first macro
call, while others, like "mm", instead require the specification of
-registers on the command line to configure paper dimensions (including
-the page offset).
+registers on the command line to configure page dimensions.
-A convenient means of setting paper dimensions when formatting is to use
-the -dpaper option of groff(1) or troff(1) together with appropriate -P
-options for the output driver (overriding the default). For example,
-use the following command for PostScript output on A4 paper in landscape
+Output drivers for typesetters also recognize command-line options `-p`
+to override the default page dimensions and `-l` to use landscape
+orientation. The output driver's man page, such as grops(1), may be
+helpful.
+
+groff's "-d paper" command-line option is a convenient means of setting
+the paper format; see groff_tmac(5). Combine it with appropriate `-P`
+options for the output driver, overriding its defaults.
+
+The following command formats for PostScript on A4 paper in landscape
orientation.
- $ groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
+ $ groff -T ps -d paper=a4l -P -pa4 -P -l -ms foo.ms > foo.ps
-See groff(1), section "Paper format"; groff_tmac(5), subsection
-"Auxiliary packages", entry "papersize"; and groff_font(5), section
-"DESC file format", entry "papersize".
+See groff(1), section "Paper format".
----------------------------------------------------------------------
diff --git a/doc/groff.texi b/doc/groff.texi
index bd9188470..186f70784 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -1591,37 +1591,39 @@ fine-tune these locations during the source
configuration process.
@cindex orientation, landscape
@cindex page orientation, landscape
-In @code{groff}, the page dimensions for the formatter GNU
-@command{troff} and for output devices are handled separately.
-@xref{Page Layout}, for vertical manipulation of the page size, and
-@ref{Line Layout}, for horizontal changes.
-@pindex papersize.tmac
-@pindex troffrc
-The @file{papersize} macro package, normally loaded by @file{troffrc} at
-startup, provides an interface for configuring page dimensions by
-convenient names, like @samp{letter} or @samp{a4}; see
-@cite{groff_tmac@r{(5)}}. The default used by the formatter depends on
-its build configuration, but is usually one of the foregoing, as
-geographically appropriate.
-@c groff(1), being generated, says what the default is.
-
-It is up to each macro package to respect the page dimensions configured
-in this way.
-
-For each output device, the size of the output medium can be set in its
-@file{DESC} file. Most output drivers also recognize a command-line
-option @option{-p} to override the default dimensions and an option
-@option{-l} to use landscape orientation. @xref{DESC File Format}, for
-a description of the @code{papersize} keyword, which takes an argument
-of the same form as @option{-p}. The output driver's man page, such as
-@cite{grops@r{(1)}}, may also be helpful.
-
-@command{groff} uses the command-line option @option{-P} to pass options
-to postprocessors; for example, use the following for PostScript output
+GNU @command{troff} reads the device description file
+@file{DESC}@footnote{@xref{Device and Font Description Files}.} for the
+selected output device when it starts; page dimensions declared there
+are used if present. @code{groff}'s build process configures a default
+page format and writes it to typesetters' @file{DESC} files. This
+installation's default is documented in @cite{gtroff@r{(1)}}. If the
+@file{DESC} file lacks this information, the formatter and output driver
+use a page length of @code{11i} (inches) for compatibility with
+@acronym{AT&T} @code{troff}.
+
+In the formatter, the @code{pl} request changes the page length, but
+macro packages often do not support alteration of the paper format
+within a document. One might, for instance, want to switch between
+portrait and landscape orientations. Macro packages lack a consistent
+approach to configuration of parameters dependent on the paper format;
+some, like @file{ms}, benefit from a preamble in the document prior to
+the first macro call, while others, like @file{mm}, instead require the
+specification of registers on the command line to configure page
+dimensions.
+
+Output drivers for typesetters also recognize command-line options
+@option{-p} to override the default page dimensions and @option{-l}
+to use landscape orientation. The output driver's man page, such as
+@cite{grops@r{(1)}}, may be helpful.
+
+@command{groff}'s @code{-d paper} command-line option is a convenient
+means of setting the paper format; see @cite{groff_tmac@r{(5)}}.
+Combine it with appropriate @option{-P} options for the output driver,
+overriding its defaults. The following command formats for PostScript
on A4 paper in landscape orientation.
@Example
-groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
+$ groff -T ps -d paper=a4l -P -pa4 -P -l -ms foo.ms > foo.ps
@endExample
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index 240cc9396..6ac01c86f 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -819,86 +819,93 @@ It is even.
.SS "Paper format"
.\" ====================================================================
.
-In GNU
-.IR roff ,
-the page dimensions for the formatter
.I @g@troff
-and for output devices are handled separately.
-.
-In the formatter,
-requests are used to set the page length
-.RB ( .pl ),
-page offset
-(or left margin,
-.BR .po ),
-and line length
-.RB ( .ll ).
-.
-The right margin is not explicitly configured;
-the combination of page offset and line length provides the information
-necessary to derive it.
+reads the device description file
+.I DESC
+for the selected output device when it starts;
+page dimensions declared there are used if present.
.
-The
-.I papersize
-macro package,
-automatically loaded by
-.IR @g@troff ,
-provides an interface for configuring page dimensions by convenient
-names,
-like \[lq]letter\[rq] or
-\[lq]A4\[rq];
-see
-.MR groff_tmac @MAN5EXT@ .
+.IR groff 's
+build process configures a default page format
+and writes it to typesetters'
+.I DESC
+files.
.
-The formatter's default in this installation is
+This installation defaults to
.RB \[lq] @PAGE@ \[rq].
.
+If the
+.I DESC
+file lacks this information,
+the formatter and output driver use a page length of 11i (inches) for
+compatibility with AT&T
+.IR troff . \" AT&T
.
-.P
-It is up to each macro package to respect the page dimensions configured
-in this way.
-.
-Some offer alternative mechanisms.
+See
+.MR groff_font @MAN5EXT@ .
.
.
.P
-For each output device,
-the size of the output medium can be set in its
-.I DESC
-file.
+In the formatter,
+the
+.B pl
+request changes the page length,
+but macro packages often do not support alteration of the paper format
+within a document.
+.
+One might,
+for instance,
+want to switch between portrait and landscape orientations.
+.
+Macro packages lack a consistent approach to configuration of parameters
+dependent on the paper format;
+some,
+like
+.IR ms ,
+benefit from a preamble in the document prior to the first macro call,
+while others,
+like
+.IR mm ,
+instead require the specification of registers on the command line to
+configure page dimensions.
+.
.
-Most output drivers also recognize a command-line option
+.P
+Output drivers for typesetters also recognize command-line options
.B \-p
-to override the default dimensions and an option
+to override the default page dimensions and
.B \-l
to use landscape orientation.
.
-See
-.MR groff_font @MAN5EXT@
-for a description of the
-.B papersize
-directive,
-which takes an argument of the same form as
-.BR \-p .
-.
The output driver's man page,
such as
.MR grops @MAN1EXT@ ,
-may also be helpful.
+may be helpful.
.
-.I groff
-uses the command-line option
+.
+.P
+.IR groff 's
+.RB \[lq] "\-d \%paper" \[rq]
+command-line option is a convenient means of setting the paper format;
+see
+.MR groff_tmac @MAN5EXT@ .
+.
+Combine it with appropriate
.B \-P
-to pass options to output devices;
-for example,
-use the following for PostScript output on A4 paper in landscape
+options for the output driver,
+overriding its defaults.
+.
+The following command formats for PostScript on A4 paper in landscape
orientation.
.
.
-.IP
+.P
+.RS
.EX
-groff \-Tps \-dpaper=a4l \-P\-pa4 \-P\-l \-ms foo.ms > foo.ps
+$ \c
+.B "groff \-T ps \-d paper=a4l \-P \-pa4 \-P \-l \-ms foo.ms > foo.ps"
.EE
+.RE
.
.
.\" ====================================================================
_______________________________________________
Groff-commit mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/groff-commit
