[groff] 17/31: [docs]: Update discussion of paper size.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 070fab2959269a793cafa60f1d02bd4251c209e1
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun May 30 11:05:37 2021 +1000

    [docs]: Update discussion of paper size.
    
    * doc/groff.texi (Paper Size): Revise for clarity and better
      organization.  Discuss the formatter, then macro packages, then output
      drivers.  Characterize `troffrc` as "normally" loading the `papersize`
      macro package by default, since the former is readily
      site-customizable.  Add cross reference to groff_tmac(5).  Explain
      valid -dpaper option values independently of what output drivers use,
      to prevent disordering of the discussion.  (Also, such concord is
      merely an implementation discipline; we do the reader no favors by
      implying a tight coupling where none architecturally exists.)  Mention
      output driver man pages explicitly.  Explain groff -P option before
      presenting example.
    
      (Line Layout): Explain absence of right margin setting (cribbed from
      ms documentation) and add concept index entries for "right margin".
    
    * src/roff/groff/groff.1.man (Usage/Paper size): Sync with the
      foregoing.
    
    * man/groff_tmac.5.man (Macro packages/Special packages) <papersize>:
      Characterize `troffrc` as "normally" loading the `papersize` macro
      package by default, since the former is readily site-customizable.
      Explicitly list supported paper size names.  Expand discussion a bit.
      Drop example duplicated from groff(1) and cross-reference back to it.
---
 doc/groff.texi             | 48 ++++++++++++++-----------
 man/groff_tmac.5.man       | 77 +++++++++++++++++++++++----------------
 src/roff/groff/groff.1.man | 89 +++++++++++++++++++++++++++++++++-------------
 3 files changed, 137 insertions(+), 77 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index b8c66de..2d89c67 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -1518,32 +1518,33 @@ those directories during the installation process.
 @cindex orientation, landscape
 @cindex page orientation, landscape
 
-In groff, the page size for @code{gtroff} and for output devices are
-handled separately.  @xref{Page Layout}, for vertical manipulation of
-the page size.  @xref{Line Layout}, for horizontal changes.
-
+In @code{groff}, the page dimensions for the formatter GNU @code{troff}
+and for output devices are handled separately.  @xref{Page Layout}, for
+vertical manipulation of the page size, and @xref{Line Layout}, for
+horizontal changes.
 @pindex papersize.tmac
 @pindex troffrc
-A convenient shorthand to set a particular paper size for @code{gtroff}
-is command-line option @option{-dpaper=@var{size}}.  This defines string
-@code{paper}, which is processed in file @file{papersize.tmac} (loaded
-in the start-up file @file{troffrc} by default).  Possible values for
-@var{size} are the same as the predefined values for the
-@code{papersize} keyword (but only in lowercase) except
-@code{a7}--@code{d7}.  An appended @samp{l} (ell) character denotes
-landscape orientation.
+The @file{papersize} macro package, normally loaded by @file{troffrc} at
+start-up, 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.
 
-It is up to the particular macro package to respect default page
-dimensions set in this way (most do).
+It is up to each macro package to respect the page dimensions configured
+in this way.
 
-A default paper size can be set in the device's @file{DESC} file.  Most
-output devices also have a command-line option @option{-p} to override
-the default paper size and option @option{-l} to use landscape
-orientation.  @xref{DESC File Format}, for a description of the
-@code{papersize} keyword, which takes the same argument as @option{-p}.
+For each output driver, the size of the output medium can be set in its
+@file{DESC} file.  Most output devices 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.
 
-For example, use the following for PS output on A4 paper in landscape
-orientation:
+@code{groff} uses the command-line option @option{-P} to pass options to
+postprocessors; for example, use the following for PostScript output on
+A4 paper in landscape orientation.
 
 @Example
 groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps
@@ -8691,6 +8692,11 @@ text is printed.
 margin.
 @end ftable
 
+@cindex margin, right
+@cindex right margin
+The right margin is not explicitly configured; the combination of page
+offset and line length provides the information necessary to derive it.
+
 A simple demonstration:
 
 @Example
diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man
index 73cb9c7..acfa310 100644
--- a/man/groff_tmac.5.man
+++ b/man/groff_tmac.5.man
@@ -343,46 +343,61 @@ See
 .
 .TP
 .I papersize
-This macro file is automatically loaded at start-up by
-.B @g@troff
-so it isn't necessary to call it explicitly.
+This macro file is normally loaded at start-up by the
+.I troffrc
+file,
+so it is seldom necessary to call it explicitly.
 .
 It provides an interface to set the paper size on the command line with
-the option \f[B]\%\-dpaper=\f[]\,\f[I]size\f[].
+the option
+.BI \-\%dpaper= size
+to
+.I groff
+or
+.IR \%@g@troff .
 .
 Possible values for
 .I size
-are the same as the predefined
-.B papersize
-values in the DESC file (only lowercase; see
-.BR groff_font (@MAN5EXT@)
-for more) except
-.BR a7 \[en] d7 .
-.
-An appended
-.B l
-(ell) character denotes landscape orientation.
-.
-Examples:
-.BR a4 ,
-.BR c3l ,
-.BR letterl .
+are the ISO and DIN formats
+\[lq]A0\[en]A6\[rq],
+\[lq]B0\[en]B6\[rq],
+\[lq]C0\[en]C6\[rq],
+and
+\[lq]D0\[en]D6\[rq];
+the U.S.\& formats
+\[lq]letter\[rq],
+\[lq]legal\[rq],
+\[lq]tabloid\[rq],
+\[lq]ledger\[rq],
+\[lq]statement\[rq],
+and
+\[lq]executive\[rq];
+and the envelope formats
+\[lq]com10\[rq],
+\[lq]monarch\[rq],
+and
+\[lq]dl\[rq].
 .
-.IP
-Most output drivers need additional command-line switches
+All formats,
+even those for envelopes,
+are in portrait orientation,
+with their longer dimension as the length.
+.
+Appending \[lq]l\[rq] (ell) to any of these denotes landscape
+orientation instead.
+.
+An output driver typically requires command-line switches
 .B \-p
 and
 .B \-l
-to override the default paper length and orientation as set in the
-driver-specific DESC file.
-.
-For example, use the following for PS output on A4 paper in landscape
-orientation:
-.
-.IP
-.EX
-\fIsh#\fP groff \-Tps \-dpaper=a4l \-P\-pa4 \-P\-l \-ms foo.ms > foo.ps
-.EE
+to override the paper dimensions and orientation,
+respectively,
+defined in its
+.I DESC
+file;
+see subsection \[lq]Paper sizes\[rq]
+of
+.IR groff (@MAN1EXT@).
 .
 .
 .TP
diff --git a/src/roff/groff/groff.1.man b/src/roff/groff/groff.1.man
index 823d7e4..0e6efc6 100644
--- a/src/roff/groff/groff.1.man
+++ b/src/roff/groff/groff.1.man
@@ -776,46 +776,85 @@ system.
 .SS "Paper size"
 .\" ====================================================================
 .
+In
+.IR groff ,
+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.
+.
 The
-.I virtual
-paper size used by
-.B troff
-to format the input is controlled globally with the requests
-.BR .po ,
-.BR .pl ,
-and
-.BR .ll .
+.I papersize
+macro package,
+automatically loaded by
+.I troffrc
+at start-up,
+provides an interface for configuring page dimensions by convenient
+names,
+like \[lq]letter\[rq] or
+\[lq]A4\[rq];
+see
+.IR groff_tmac (@MAN5EXT@).
 .
-See
-.BR groff_tmac (@MAN5EXT@)
-for the \[oq]papersize\[cq] macro package which provides a convenient
-interface.
+The default used by the formatter depends on its build configuration,
+but is usually one of the foregoing,
+as geographically appropriate.
 .
 .
 .P
-The
-.I physical
-paper size, giving the actual dimensions of the paper sheets, is
-controlled by output devices like
-.B grops
-with the command-line options
+It is up to each macro package to respect the page dimensions configured
+in this way.
+.
+.
+.P
+For each output driver,
+the size of the output medium can be set in its
+.I DESC
+file.
+.
+Most output devices also recognize a command-line option
 .B \-p
-and
-.BR \-l .
+to override the default dimensions and an option
+.B \-l
+to use landscape orientation.
 .
 See
-.BR groff_font (@MAN5EXT@)
-and the man pages of the output devices for more details.
+.IR groff_font (@MAN5EXT@)
+for a description of the
+.B papersize
+keyword,
+which takes an argument of the same form as
+.BR \-p .
+.
+The output driver's man page,
+such as
+.IR grops (@MAN1EXT@),
+may also be helpful.
 .
 .B groff
 uses the command-line option
 .B \-P
-to pass options to output devices; for example, the following selects
-A4 paper in landscape orientation for the PS device:
+to pass options to output devices;
+for example,
+use the following for PostScript output on A4 paper in landscape
+orientation.
+.
 .
 .IP
 .EX
-groff \-Tps \-P\-pa4 \-P\-l ...
+groff \-Tps \-dpaper=a4l \-P\-pa4 \-P\-l \-ms foo.ms > foo.ps
 .EE
 .
 .