[groff] 18/40: [docs]: Present several fundamental concepts.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 1228acc430b2b9638c598a223496ceebfed778af
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Feb 3 04:05:14 2022 +1100

    [docs]: Present several fundamental concepts.
    
    * doc/groff.texi (Page Geometry):
    * man/roff.7.man (Concepts): Add new node/section defining concepts.
      - device resolution
      - basic units
      - drawing position
      - text baseline
      - page offset
      - vertical spacing
      - vee
      - page break
    
    Also:
    * doc/groff.texi: Bump date.  Add an authorship credit for myself.
    
    $ git diff --stat 1.22.4 HEAD doc/groff.texi
     doc/groff.texi | 13649 ++++++++++++++++++++++++++---------------------
     1 file changed, 7578 insertions(+), 6071 deletions(-)
    
    * doc/groff.texi:
    * man/roff.7.man: Bump copyright notice.
---
 ChangeLog      |  15 ++++++
 doc/groff.texi |  97 ++++++++++++++++++++++++++++++++---
 man/roff.7.man | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---
 3 files changed, 258 insertions(+), 12 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index d77ecee7..8e5c1bb9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2022-02-03  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [docs]: Present several fundamental concepts.
+
+       * doc/groff.texi (Page Geometry):
+       * man/roff.7.man (Concepts): Add new node/section.
+         - page geometry
+         - basic units
+         - device resolution
+         - drawing position
+         - text baseline
+         - page offset
+         - vertical spacing
+         - page break
+
 2022-02-02  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        [me]: Add page length insufficiency check.
diff --git a/doc/groff.texi b/doc/groff.texi
index 630752c3..4f9affb1 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -26,7 +26,7 @@
 @copying
 This manual documents GNU @code{troff} version 1.23.0.
 
-Copyright @copyright{} 1994--2021 Free Software Foundation, Inc.
+Copyright @copyright{} 1994--2022 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -468,9 +468,10 @@ developing GNU and promoting software freedom.''
 @title groff
 @subtitle The GNU implementation of @code{troff}
 @subtitle Edition 1.23.0
-@subtitle January 2022
-@author by Trent A.@tie{}Fisher
-@author and Werner Lemberg
+@subtitle February 2022
+@author Trent A.@tie{}Fisher
+@author Werner Lemberg
+@author G.@tie{}Branden Robinson
 
 @page
 @vskip 0pt plus 1filll
@@ -4654,6 +4655,7 @@ not interested in details.
 
 @menu
 * Text::
+* Page Geometry::
 * Measurements::
 * Expressions::
 * Identifiers::
@@ -5454,6 +5456,90 @@ later.
 .\" Albert Einstein, _The Meaning of Relativity_, 1922
 @endCartoucheExample
 
+@node Page Geometry, Measurements, Text, gtroff Reference
+@section Page Geometry
+@cindex page, geometry of
+@cindex geometry, page
+
+@code{roff} systems format text under certain assumptions about the size
+of the output medium, or page.  For the formatter to correctly break a
+line it is filling, it must know the line length, which it derives from
+the page width (@pxref{Line Layout}).  For it to decide whether to write
+an output line to current page or wait until the next one, it must know
+the page length (@pxref{Page Layout}).
+
+@cindex device resolution
+@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.
+
+@cindex drawing position
+@cindex position, drawing
+While the formatter (and, later, output driver) is processing a page, it
+keeps track of its @dfn{drawing position}, 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.
+@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
+``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.
+
+@cindex page offset
+@cindex offset, page
+Such a situation is nearly always undesirable.  It is furthermore
+conventional not to write or draw at the extreme edges of the page.
+Therefore the initial drawing position of a @code{roff} formatter is not
+at the origin, but down and to the right of it.  This rightward shift
+from the left edge is known as the @dfn{page
+offset}.@footnote{@code{groff}'s terminal output devices have page
+offsets of zero.}  The downward shift leaves room for a text output
+line.
+
+Text is arranged on a one-dimensional lattice of text baselines from the
+top to the bottom of the page.
+@cindex vertical spacing
+@cindex spacing, vertical
+@cindex vee
+@dfn{Vertical spacing} is the distance between adjacent text baselines.
+In ordinary circumstances, this quantity is tightly coupled to the type
+size.  The initial drawing position is one unit of vertical spacing
+below the page top.  Typographers have a name for this unit:@: ``vee''.
+
+@cindex page break
+@cindex break, page
+Vertical spacing has an impact on page-breaking decisions.  Generally,
+when a break occurs, the formatter moves the drawing position to the
+next text baseline automatically.  If the formatter was already writing
+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 above the
+page top again; this is called 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
+programming ``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
 @codequoteundirected off
 
@@ -5579,8 +5665,7 @@ Ens.  In @code{groff}, this is half of an em.
 @cindex space, vertical, unit (@code{v})
 @cindex @code{v} unit
 @cindex unit, @code{v}
-Vertical space.  This is equivalent to the current line spacing.
-@xref{Sizes}.
+Vees.  @xref{Page Geometry}.
 
 @item M
 @cindex @code{M} unit
diff --git a/man/roff.7.man b/man/roff.7.man
index cd2ae6a9..5f03383c 100644
--- a/man/roff.7.man
+++ b/man/roff.7.man
@@ -11,7 +11,7 @@ roff \- concepts and history of roff typesetting
 .\" Legal Terms
 .\" ====================================================================
 .\"
-.\" Copyright (C) 2000-2020 Free Software Foundation, Inc.
+.\" Copyright (C) 2000-2022 Free Software Foundation, Inc.
 .\"
 .\" This file is part of groff, the GNU roff type-setting system.
 .\"
@@ -90,11 +90,155 @@ and recommends materials for further reading.
 .
 .
 .\" ====================================================================
-.\"SH Concepts
+.SH Concepts
 .\" ====================================================================
-.\"
-.\" (text) baseline
-.\" vertical spacing
+.
+.\" TODO: Break this into subsections when we get more material.
+.\" BEGIN Keep parallel with groff.texi node "Page Geometry".
+.I roff
+systems format text under certain assumptions about the size of the
+output medium,
+or page.
+.
+For the formatter to correctly break a line it is filling,
+it must know the line length,
+which it derives from the page width.
+.\" (@pxref{Line Layout}).
+.
+For it to decide whether to write an output line to the current page or
+wait until the next one,
+it must know the page length.
+.\" (@pxref{Page Layout}).
+.
+.
+A device's
+.I resolution
+enables conversion of practical units like inches or centimeters to
+.I 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
+(see
+.MR groff_font @MAN5EXT@ )
+.\" (@pxref{DESC File Format}).
+.
+A 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.
+.
+Useful coordinate values are therefore always positive and within the
+range of the page boundaries.
+.
+.
+.P
+While the formatter
+(and,
+later,
+output driver)
+is processing a page,
+it keeps track of its
+.I drawing position,
+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.
+.RI ( groff
+does not yet support right-to-left scripts.)
+.
+The
+.I text baseline
+is a
+(usually invisible)
+line upon which the glyphs of a typeface \[lq]sit\[rq].
+.
+A glyph therefore \[lq]starts\[rq] 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 \[lq]g\[rq],
+it features a decender below the baseline.
+.
+.
+.P
+Such a situation is nearly always undesirable.
+.
+It is furthermore conventional not to write or draw at the extreme edges
+of the page.
+.
+Therefore the initial drawing position of a
+.I roff
+formatter is not at the origin,
+but down and to the right of it.
+.
+This rightward shift
+from the left edge is known as the
+.I page offset.
+.
+.RI ( groff 's
+terminal output devices have page offsets of zero.)
+.
+The downward shift leaves room for a text output line.
+.
+.
+.P
+Text is arranged on a one-dimensional lattice of text baselines from
+the top to the bottom of the page.
+.
+.I Vertical spacing
+is the distance between adjacent text baselines.
+.
+In ordinary circumstances,
+this quantity is tightly coupled to the type size.
+.
+The initial vertical drawing position is one unit of vertical spacing
+below the page top.
+.
+Typographers have a name for this unit:
+\[lq]vee\[rq].
+.
+.
+.P
+Vertical spacing has an impact on page-breaking decisions.
+.
+Generally,
+when a break occurs,
+the formatter moves the drawing position to the next text baseline
+automatically.
+.
+If the formatter was already writing 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,
+.I roff
+formatters instruct the output driver to eject the page,
+start a new one,
+and reset the drawing position to one vee above the page top again;
+this is called 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.
+.
+Macro packages keep users from having
+to confront this difficulty by programming \[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.
+.\" END Keep parallel with groff.texi node "Page Geometry".
 .
 .
 .\" ====================================================================
@@ -1645,7 +1789,9 @@ This document was written by
 .MT groff\-bernd\:.warken\-72@\:web\:.de
 Bernd Warken
 .ME ,
-with the sections \[lq]History\[rq] and \[lq]Input Conventions\[rq]
+with the sections \[lq]Concepts\[rq],
+\[lq]History\[rq],
+and \[lq]Input Conventions\[rq]
 mostly written by
 .MT g.branden\:.robinson@\:gmail\:.com
 G.\& Branden Robinson