[groff] 39/41: doc/groff.texi: Fix style nits.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit df0e07131db181a94191a63b0f292c52f5676c3d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Mar 18 02:15:57 2022 +1100

    doc/groff.texi: Fix style nits.
    
    (Macro Packages):
    * Clarify and tighten wording.
    
    (Page Geometry):
    * Tighten wording.
    * Add "page" to the concept index.  Split definition of "page" into its
      own paragraph and document positive direction of coordinate axes.
    * Recast discussion of text baseline and (notional) glyph drawing.
    * Simplify discussion of consequences of breaking less than 1v from the
      end of a page.
    
    (Default Units):
    * Clarify discussion of dimensionless arithmetic.
    * Migrate terminology: "scaling indicator" -> "scaling unit".  (This
      node needs further revision.)
    
    (Identifiers):
    * Tweak wording.
    
    (Embedded Commands):
    * Recast introduction to section.
    * Add inter-sentence space supplementation as a basic formatting
      operation.
    * Fix typo.
    
    * man/groff.7.man (Identifiers):
    * man/roff.7.man (Page geometry): Sync with our Texinfo manual changes.
---
 doc/groff.texi  | 81 +++++++++++++++++++++++++++++++--------------------------
 man/groff.7.man |  2 +-
 man/roff.7.man  | 36 +++++++++++++------------
 3 files changed, 65 insertions(+), 54 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index a88893aa..a804739b 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -5221,8 +5221,8 @@ appended to), requests are not interpreted and macros not 
interpolated,
 whereas some commonly used escape sequences @emph{are} interpolated.
 @code{roff} systems also support recursive macros---as long as you have
 a way to break the recursion (@pxref{Conditionals and Loops}).  For
-maintainable @code{roff} documents, arrange your macro definitions so
-that they are most easily understood when read from beginning to end.
+maintainable @code{roff} documents, arrange your macro definitions to
+minimize forward references.
 
 @c ---------------------------------------------------------------------
 
@@ -5493,15 +5493,18 @@ know the page length (@pxref{Page Layout}).
 @cindex resolution, device
 @cindex basic units
 @cindex units, basic
-A device's @dfn{resolution} enables conversion of practical units like
-inches or centimeters to @dfn{basic units}, a convenient length measure
-for the output device or file format.  The formatter and output driver
-use basic units to reckon page measurements.  The device description
-file defines its resolution and page dimensions (@pxref{DESC File
-Format}).  A page is a two-dimensional structure upon which a
-@code{roff} system imposes a coordinate system in basic units with its
-upper left corner as the origin.  Useful coordinate values are therefore
-always positive and within the range of the page boundaries.
+A device's @dfn{resolution} converts practical units like inches or
+centimeters to @dfn{basic units}, a convenient length measure for the
+output device or file format.  The formatter and output driver use basic
+units to reckon page measurements.  The device description file defines
+its resolution and page dimensions (@pxref{DESC File Format}).
+
+@cindex page
+A @dfn{page} is a two-dimensional structure upon which a @code{roff}
+system imposes a coordinate system with its upper left corner as the
+origin.  Coordinate values are in basic units and increase down and to
+the right.  Useful ones are therefore always positive and within numeric
+ranges corresponding to the page boundaries.
 
 @cindex drawing position
 @cindex position, drawing
@@ -5511,10 +5514,10 @@ which the next glyph will be written, from which the 
next motion will be
 measured, or where a geometric primitive will commence rendering.
 @cindex text baseline
 @cindex baseline, text
-By convention, glyphs are drawn from a text baseline upward and
-to the right.@footnote{@code{groff} does not yet support right-to-left
-scripts.}  The @dfn{text baseline} is a (usually invisible) line
-upon which the glyphs of a typeface ``sit''.  A glyph therefore
+Notionally, glyphs are drawn from the text baseline upward and to the
+right.@footnote{@code{groff} does not yet support right-to-left
+scripts.}  The @dfn{text baseline} is a (usually invisible) line upon
+which the glyphs of a typeface are aligned.  A glyph therefore
 ``starts'' at its bottom-left corner.  If drawn at the origin, a typical
 letter glyph would lie partially or wholly off the page, depending on
 whether, like ``g'', it features a decender below the baseline.
@@ -5549,16 +5552,15 @@ to the last line that would fit on the page, advancing 
by one vee would
 place the next text baseline off the page.  Rather than let that happen,
 @code{roff} formatters instruct the output driver to eject the page,
 start a new one, and reset the drawing position to one vee below the
-page top again; this is called a @dfn{page break}.
+page top again; this is a @dfn{page break}.
 
 When the last line of input text is also the last output line that can
-fit on the page, the break caused by the last newline of the input file
-@c (or end-of-file status)
-will also cause a page break, causing a useless blank page to be output.
-Macro packages keep users from having to confront this difficulty by
-setting ``traps'' (@pxref{Traps}); moreover, all but the simplest page
-layouts tend to have headers and footers or at least bear vertical
-margins larger than one vee.
+fit on the page, the break caused by the end of the input file will also
+break the page, producing a useless blank one.  Macro packages keep
+users from having to confront this difficulty by setting ``traps''
+(@pxref{Traps}); moreover, all but the simplest page layouts tend to
+have headers and footers, or at least bear vertical margins larger than
+one vee.
 
 
 @codequotebacktick off
@@ -5730,8 +5732,8 @@ parenthesis is simply ignored.
 
 @cindex measurements, specifying safely
 Thus, the safest way to specify measurements is to always attach a
-scaling indicator.  If you want to multiply or divide by a certain
-scalar value, use @samp{u} as the unit for that value.
+scaling unit.  To multiply or divide by a dimensionless value, use
+@samp{u} as its unit.
 
 @codequotebacktick on
 @codequoteundirected on
@@ -6088,7 +6090,7 @@ sets ``C0 Controls'' and ``C1 Controls'' as Unicode 
describes them).
 When GNU @code{troff} encounters one in an identifier, it produces a
 warning diagnostic of type @samp{input} (@pxref{Debugging}).  They are
 removed during parsing; an identifier @samp{foo}, followed by an invalid
-character, followed by @samp{bar}, is treated as @samp{foobar}.
+character, followed by @samp{bar}, is interpreted as @samp{foobar}.
 
 On a machine using the ISO 646, 8859, or 10646 character encodings,
 invalid input characters are @code{0x00}, @code{0x08}, @code{0x0B},
@@ -6244,19 +6246,24 @@ emitted!  The contents of the first macro definition 
are lost.
 @cindex embedded commands
 @cindex commands, embedded
 
-To support the needs of documents that require more than filling,
-automatic line breaking and hyphenation, and adjustment, GNU
-@code{troff} allows commands to be embedded into the text.  This is
-done in two ways.
+To support documents that require more than filling, automatic line
+breaking and hyphenation, adjustment, and supplemental inter-sentence
+space, GNU @code{troff} allows instructions to the formatter to be
+embedded into the text.  This is done in two ways.
 
-One is a @dfn{request} that takes up an entire line, and often performs
-some large-scale operation such as breaking a lines or starting a new
-page.
+One is a @dfn{request}, which begins with a control character and takes
+up an entire input line.  Requests often perform relatively large-scale
+operations such as setting the page length, breaking a line, or starting
+a new page.
+
+The other is an @dfn{escape sequence}, which begins with the escape
+character and can usually be embedded anywhere in the text, even in
+arguments to requests and other escape sequences.  Escape sequences
+often implement relatively minor operations like sub- and superscripting
+or interpolating a symbol.
 
-The other is an @dfn{escape sequence} that can usually be embedded
-anywhere in the text; most requests can accept an escape even as an
-argument.  Escape sequences typically implement relatively minor
-operations like sub- and superscripting or interpolating a symbol.
+Some operations are available via both requests and escape sequences,
+such as font selection and type size alteration.
 
 @menu
 * Requests::
diff --git a/man/groff.7.man b/man/groff.7.man
index 7264d46f..6b9a1c88 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -4436,7 +4436,7 @@ an identifier
 followed by an invalid character,
 followed by
 .RB \[lq] bar \[rq]
-is treated as
+is interpreted as
 .RB \[lq] foobar \[rq] .
 .
 .
diff --git a/man/roff.7.man b/man/roff.7.man
index d6b84e59..368343f1 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -373,7 +373,7 @@ it must know the page length.
 .
 A device's
 .I resolution
-enables conversion of practical units like inches or centimeters to
+converts practical units like inches or centimeters to
 .I basic units,
 a convenient length measure for the output device or file format.
 .
@@ -385,13 +385,18 @@ The device description file defines its resolution and 
page dimensions
 .MR groff_font @MAN5EXT@ ).
 .\" (@pxref{DESC File Format}).
 .
-A page is a two-dimensional structure upon which a
+.
+.P
+A
+.I page
+is a two-dimensional structure upon which a
 .I roff
-system imposes a coordinate system in basic units with its upper left
-corner as the origin.
+system imposes a coordinate system with its upper left corner as the
+origin.
 .
-Useful coordinate values are therefore always positive and within the
-range of the page boundaries.
+Coordinate values are in basic units and increase down and to the right.
+Useful ones are therefore always positive and within numeric ranges
+corresponding to the page boundaries.
 .
 .
 .P
@@ -406,8 +411,8 @@ which is the location at which the next glyph will be 
written,
 from which the next motion will be measured,
 or where a geometric primitive will commence rendering.
 .
-By convention,
-glyphs are drawn from a text baseline upward and to the right.
+Notionally,
+glyphs are drawn from the text baseline upward and to the right.
 .RI ( groff
 does not yet support right-to-left scripts.)
 .
@@ -415,7 +420,7 @@ The
 .I text baseline
 is a
 (usually invisible)
-line upon which the glyphs of a typeface \[lq]sit\[rq].
+line upon which the glyphs of a typeface are aligned.
 .
 A glyph therefore \[lq]starts\[rq] at its bottom-left corner.
 .
@@ -481,24 +486,23 @@ Rather than let that happen,
 formatters instruct the output driver to eject the page,
 start a new one,
 and reset the drawing position to one vee below the page top again;
-this is called a
+this is a
 .I page break.
 .
 .
 .P
 When the last line of input text is also the last output line that can
 fit on the page,
-the break caused by the last newline of the input file
-.\" (or end-of-file status)
-will also cause a page break,
-causing a useless blank page to be output.
+the break caused by the end of the input file
+will also break the page,
+producing a useless blank one.
 .
 Macro packages keep users from having
 to confront this difficulty by setting \[lq]traps\[rq];
 .\" (@pxref{Traps});
 moreover,
-all but the simplest page layouts tend to have headers and footers or at
-least bear vertical margins larger than one vee.
+all but the simplest page layouts tend to have headers and footers,
+or at least bear vertical margins larger than one vee.
 .\" END Keep parallel with groff.texi node "Page Geometry".
 .
 .