[groff] 08/35: [man pages]: Update paper size discussion.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c287f385ffaa8ad1fcb5695e9a1612f525a8afd7
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Wed Jul 14 23:16:21 2021 +1000

    [man pages]: Update paper size discussion.
    
    * man/groff_font.5.man (Description/DESC file format)
      <paperlegth, paperwidth>: Say "basic" instead of "machine" units.
      <papersize>: Clarify: it's troff(1) that parses the DESC file, not
      groff(1).  Recognize that D0-D7 paper formats are DIN, not ISO.  Add
      comment noting implementation discrepancy: papersize.tmac doesn't
      support [ABCD]7 paper formats.  Move "DL" to list of envelope formats
      and capitalize it.  Fix grammar nits.
    
    * man/groff_tmac.5.man (Macro packages/Special packages) <papersize>:
      Add comment noting implementation discrepancy: libgroff also supports
      [ABCD]7 paper formats.  Move "DL" to list of envelope formats and
      capitalize it.
    
    * doc/groff.texi (DESC File Format) <paperlength, papersize,
      paperwidth>: Sync with groff_font(5) above.
---
 doc/groff.texi       | 44 ++++++++++++++++++++++----------------------
 man/groff_font.5.man | 48 ++++++++++++++++++++++++++----------------------
 man/groff_tmac.5.man |  3 ++-
 3 files changed, 50 insertions(+), 45 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index a95603e..76cc62d 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -17773,36 +17773,36 @@ another name.
 @item paperlength @var{n}
 @kindex paperlength
 The physical vertical dimension of the output medium in basic units.
-This isn't used by @code{troff} itself but by output devices.
+This isn't used by GNU @code{troff} itself, but by output devices.
 Deprecated.  Use @code{papersize} instead.
 
 @item papersize @var{string} @dots{}
 @kindex papersize
-Select a paper size.  Valid values for @var{string} are the ISO paper
-types @code{A0}--@code{A7}, @code{B0}--@code{B7}, @code{C0}--@code{C7},
-@code{D0}--@code{D7}, @code{DL}, and the US paper types @code{letter},
-@code{legal}, @code{tabloid}, @code{ledger}, @code{statement},
-@code{executive}, @code{com10}, and @code{monarch}.  Case is not
-significant for @var{string} if it holds predefined paper types.
-Alternatively, @var{string} can be a file name (e.g.@:
-@file{/etc/papersize}); if the file can be opened, @code{groff} reads
-the first line and tests for the above paper sizes.  Finally,
-@var{string} can be a custom paper size in the format
-@code{@var{length},@var{width}} (no spaces before and after the comma).
-Both @var{length} and @var{width} must have a unit appended; valid
-values are @samp{i} for inches, @samp{c} for centimeters, @samp{p} for
-points, and @samp{P} for picas.  Example: @code{12c,235p}.  An argument
-that starts with a digit is always treated as a custom paper format.
-@code{papersize} sets both the vertical and horizontal dimension of the
-output medium.
-
-More than one argument can be specified; @code{groff} scans from left to
-right and uses the first valid paper specification.
+Select a paper size.  Valid values for @var{string} are the ISO and DIN
+formats @code{A0}--@code{A7}, @code{B0}--@code{B7}, @code{C0}--@code{C7},
+@code{D0}--@code{D7}; the U.S.@: paper types @code{letter},
+@code{legal}, @code{tabloid}, @code{ledger}, @code{statement}, and
+@code{executive}; and the envelope formats @code{com10}, @code{monarch},
+and @code{DL}.  Case is not significant for @var{string} if it holds
+predefined paper types.  Alternatively, @var{string} can be a file name
+(e.g., @file{/etc/papersize}); if the file can be opened, GNU
+@code{troff} reads the first line and tests for the above paper sizes.
+Finally, @var{string} can be a custom paper size in the format
+@code{@var{length},@var{width}} (with no spaces before or after the
+comma).  Both @var{length} and @var{width} must have a unit appended;
+valid values are @samp{i} for inches, @samp{c} for centimeters, @samp{p}
+for points, and @samp{P} for picas.  Example: @code{12c,235p}.  An
+argument that starts with a digit is always treated as a custom paper
+format.  @code{papersize} sets both the vertical and horizontal
+dimensions of the output medium.
+
+More than one argument can be specified; GNU @code{troff} scans from
+left to right and uses the first valid paper specification.
 
 @item paperwidth @var{n}
 @kindex paperwidth
 The physical horizontal dimension of the output medium in basic units.
-This isn't used by @code{troff} itself but by output devices.
+This isn't used by GNU @code{troff} itself, but by output devices.
 Deprecated.  Use @code{papersize} instead.
 
 @item pass_filenames
diff --git a/man/groff_font.5.man b/man/groff_font.5.man
index c6b417c..1428d12 100644
--- a/man/groff_font.5.man
+++ b/man/groff_font.5.man
@@ -153,7 +153,7 @@ it might be set to another name.
 .
 .TP
 .BI paperlength\~ n
-The physical vertical dimension of the output medium in machine units.
+The physical vertical dimension of the output medium in basic units.
 .
 This isn't used by
 .I \%@g@troff
@@ -171,24 +171,28 @@ instead.
 .BI papersize\~ string
 Select a paper size.
 .
-Valid values for
+Valid values of
 .I string
-are the ISO paper types
+are the ISO and DIN formats
 .BR A0 \[en] A7 ,
 .BR B0 \[en] B7 ,
 .BR C0 \[en] C7 ,
-.BR D0 \[en] D7 ,
-.BR DL ,
-and the U.S.\& paper types
+and
+.BR D0 \[en] D7 ;
+.\" XXX: tmac/papersize.tmac does not support [ABCD]7.
+the U.S.\& formats
 .BR letter ,
 .BR legal ,
 .BR tabloid ,
 .BR ledger ,
 .BR statement ,
-.BR executive ,
+and
+.BR executive ;
+and the envelope formats
 .BR com10 ,
+.BR monarch ,
 and
-.BR monarch .
+.BR DL .
 .
 Case is not significant for
 .I string
@@ -200,24 +204,24 @@ can be a file name
 (e.g.,
 .IR /etc/papersize );
 if the file can be opened,
-.I groff
+.I \%@g@troff
 reads the first line and tests for the above paper sizes.
 .
 Finally,
 .I string
 can be a custom paper size in the format
 .IB length , width
-(no spaces before and after the comma).
+(with no spaces before or after the comma).
 .
 Both
 .I length
 and
 .I width
 must have a unit appended;
-valid values are \[oq]i\[cq] for inches,
-\[oq]c\[cq] for centimeters,
-\[oq]p\[cq] for points,
-and \[oq]P\[cq] for picas.
+valid values are \[lq]i\[rq] for inches,
+\[lq]c\[rq] for centimeters,
+\[lq]p\[rq] for points,
+and \[lq]P\[rq] for picas.
 .
 Example:
 .BR 12c,235p .
@@ -226,17 +230,22 @@ An argument which starts with a digit is always treated 
as a custom
 paper format.
 .
 .B papersize
-sets both the vertical and horizontal dimension of the output medium.
+sets both the vertical and horizontal dimensions of the output medium.
 .
 .IP
 More than one argument can be specified;
-.I groff
+.I \%@g@troff
 scans from left to right and uses the first valid paper specification.
 .
 .
 .TP
 .BI paperwidth\~ n
-The physical horizontal dimension of the output medium in machine units.
+The physical horizontal dimension of the output medium in basic units.
+.
+This isn't used by
+.I \%@g@troff
+itself,
+but by output devices.
 .
 Deprecated.
 .
@@ -244,11 +253,6 @@ Use
 .B papersize
 instead.
 .
-This isn't used by
-.I \%@g@troff
-itself,
-but by output devices.
-.
 .
 .TP
 .B pass_filenames
diff --git a/man/groff_tmac.5.man b/man/groff_tmac.5.man
index eaf050a..c37beb9 100644
--- a/man/groff_tmac.5.man
+++ b/man/groff_tmac.5.man
@@ -502,6 +502,7 @@ are the ISO and DIN formats
 \[lq]C0\[en]C6\[rq],
 and
 \[lq]D0\[en]D6\[rq];
+.\" XXX: src/libs/libgroff/paper.cpp also supports [ABCD]7.
 the U.S.\& formats
 \[lq]letter\[rq],
 \[lq]legal\[rq],
@@ -514,7 +515,7 @@ and the envelope formats
 \[lq]com10\[rq],
 \[lq]monarch\[rq],
 and
-\[lq]dl\[rq].
+\[lq]DL\[rq].
 .
 All formats,
 even those for envelopes,