[groff] 04/17: [docs]: Improve discussion of `fzoom` request.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit f03e6f62e1b9b3c4bb4a267b26e376d5f050a82c
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Aug 4 09:53:35 2023 -0500

    [docs]: Improve discussion of `fzoom` request.
    
    What does it really mean for this request to be "transparent" to the
    formatter?  ("Transparent" has to be one of the most overloaded, abused,
    and unhelpful words in groff's documentary corpus.  I am starting to
    think it is a placeholder term for anything the writer couldn't figure
    out how to explain.)
    
    Also, put the example of usage after the full discussion of request
    behavior, including input validity constraints.  Improve the example to
    illustrate a _practical_ application of this request.
    
    Try to clarify.  A telling experiment follows.
    
    $ cat EXPERIMENTS/fzoom-width.groff
    The width of foo is \w'foo' at \n[.ps] scaled points.
    .sp
    .ps 20
    .vs 24
    The width of foo is \w'foo' at \n[.ps] scaled points.
    .sp
    .ps 10
    .vs 12
    .fzoom TR 2000
    The width of foo is \w'foo' at \n[.ps] scaled points.
    $ groff -a EXPERIMENTS/fzoom-width.groff
    <beginning of page>
    The width of foo is 13330 at 10000 scaled points.
    The width of foo is 26660 at 20000 scaled points.
    The width of foo is 26660 at 10000 scaled points.
    
    Bump document date.
---
 doc/groff.texi  | 49 ++++++++++++++++++++++++++-----------------------
 man/groff.7.man | 11 ++++++-----
 2 files changed, 32 insertions(+), 28 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 605d526f9..68ba3672a 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -464,7 +464,7 @@ Documentation License''.
 @title groff
 @subtitle The GNU implementation of @code{troff}
 @subtitle Edition 1.23.0+Git
-@subtitle July 2023
+@subtitle August 2023
 @author Trent@tie{}A.@: Fisher
 @author Werner Lemberg
 @author G.@tie{}Branden Robinson
@@ -10405,7 +10405,7 @@ is undone.
 @c styles?
 @endDefreq
 
-@DefreqList {fzoom, f [@Var{zoom}]}
+@DefreqList {fzoom, font [@Var{zoom}]}
 @DefregListEndx {.zoom}
 @cindex magnification of a font (@code{fzoom})
 @cindex font, magnification (@code{fzoom})
@@ -10415,29 +10415,32 @@ is undone.
 @cindex optical size of a font
 @cindex font, optical size
 @cindex size, optical, of a font
-Set magnification of font@tie{}@var{f} to factor @var{zoom}, which must
-be a non-negative integer, a multiplier of the current type size in
-thousandths.  @code{fzoom} adjusts the apparent size of a font in
-relation to others.  In the example below, font @code{CR} is magnified
-by 10% (the zoom factor is thus 1.1).
-
-@Example
-.fam P
-.fzoom CR 1100
-.ps 12
-Palatino and \f[CR]Courier\f[]
+Set magnification of mounted @var{font} to factor @var{zoom}, a
+multiplier applied to the type size in thousandths.  @var{zoom} must be
+non-negative.  @code{fzoom} applies to glyphs when they are formatted,
+altering a font's apparent size in relation to others.  A missing or
+zero @var{zoom} is treated as @samp{1000}---no magnification.
+@var{font} must be a resolved font name, not an abstract style.
+
+Font magnification is transparent to GNU @code{troff}; a change of the
+zoom factor affects scaling of glyph sizes, inter-word and
+inter-sentence spaces, and kerning adjustments on the output device.  It
+is not reflected in registers that report the requested or current type
+size, or the measurements reported by the @code{\w} escape sequence.
+
+@code{fzoom} can harmonize the apparent cap-heights of fonts from
+different families when formatted on the same baseline.
+
+@Example
+.fzoom HR 900
+.fzoom CR 1150
+.fzoom PR 950
+Times, \F[H]Helvetica\F[], \F[C]Courier\F[],
+and \F[P]Palatino\F[].
+.sp
+M\F[H]M\F[C]M\F[P]M
 @endExample
 
-A missing or zero value of @var{zoom} is treated as @samp{1000}, meaning
-no magnification.  @var{f}@tie{}must be a resolved font name, not an
-abstract style.
-@c XXX: What about a mounting position?  It's not rejected...
-
-The magnification of a font is transparent to GNU @code{troff}; a change
-of the zoom factor doesn't cause any effect except that the dimensions
-of glyphs, (word) spaces, kerns, etc., of the affected font are adjusted
-accordingly.
-
 The zoom factor of the current font is available in the read-only
 register @samp{.zoom}.  It interpolates zero if there is no
 magnification.
diff --git a/man/groff.7.man b/man/groff.7.man
index acef6f6c4..e239d8f4b 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -3204,12 +3204,13 @@ Stop magnifying
 .IR font .
 .
 .TPx
-.REQ .fzoom "font z"
-Set zoom factor for
+.REQ .fzoom "font zoom"
+Set magnification of mounted
 .I font
-.RI to\~ z
-(in thousandths;
-default:
+to
+.IR zoom ,
+a multiplier of the current type size in thousandths
+(default:
 1000).
 .
 .TPx