[groff] 11/28: [me]: Rename registers `$v` -> `tv`, `$V` -> `dv`.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 47600ca4849ae504bb8fb9ae591de551dd1ee357
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sat Feb 12 08:48:44 2022 +1100

    [me]: Rename registers `$v` -> `tv`, `$V` -> `dv`.
    
    * tmac/e.tmac: Do it.  Also include much commentary (including some from
      James Clark in 1992) attempting to illuminate the confusing history
      (and naming) of `$[rRvR]`.
    
    * doc/meref.me.in: Document it.  Introduce new terms "text vertical
      spacing" and "display vertical spacing" earlier and use them to
      condense and clarify discussions of their use.
    
    * NEWS: Add item.
    
    Fixes <https://savannah.gnu.org/bugs/?61710>.
---
 ChangeLog       | 16 ++++++++++++++
 NEWS            |  9 +++++++-
 doc/meref.me.in | 43 +++++++++++++++----------------------
 tmac/e.tmac     | 66 ++++++++++++++++++++++++++++++++++++---------------------
 4 files changed, 83 insertions(+), 51 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 1cb57a5f..e15e5259 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2022-02-12  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [me]: Rename registers `$v` -> `tv`, `$V` -> `dv`.
+
+       * tmac/e.tmac: Do it.  Also include much commentary (including
+       some from James Clark in 1992) attempting to illuminate the
+       confusing history (and naming) of `$[rRvR]`.
+
+       * doc/meref.me.in: Document it.  Introduce new terms
+       "text vertical spacing" and "display vertical spacing" earlier
+       and use them to condense and clarify discussions of their use.
+
+       * NEWS: Add item.
+
+       Fixes <https://savannah.gnu.org/bugs/?61710>.
+
 2022-02-09  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * doc/groff.texi (Deferring Output): Add new node introducing
diff --git a/NEWS b/NEWS
index 5f82182a..c09bd17b 100644
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,4 @@
-    Copyright (C) 1992-2021 Free Software Foundation, Inc.
+    Copyright (C) 1992-2022 Free Software Foundation, Inc.
 
     Copying and distribution of this file, with or without modification,
     are permitted in any medium without royalty provided the copyright
@@ -270,6 +270,13 @@ o The e (me) macro package now has a register `sx` that 
eases the
   literally in past definitions of the super/subscripting strings.
   groff's own 'me' documents redefine it to zero.
 
+o The e (me) macro package's `$v` and `$V` registers have been renamed
+  to `tv` and `dv`--they control the vertical spacing used
+  for text and displays/annotations, respectively.  The old names are
+  still supported as aliases.  The new names reflect the fact that users
+  are expected to set them if desired, unlike other registers and
+  strings beginning with "$".
+
 o The m (mm) macro package now requires a title to be declared when
   memorandum type 5 is used (".MT 5"), just as type 4 has since groff
   1.10 (November 1995).
diff --git a/doc/meref.me.in b/doc/meref.me.in
index 55d0cbd8..f4b96d30 100644
--- a/doc/meref.me.in
+++ b/doc/meref.me.in
@@ -684,13 +684,16 @@ of vertical space
 and use a
 vertical spacing
 (distance between text baselines)
+as a percentage of the type size
 of
-.NR ($V .
+.NR (dv
+[120].
 Long quotation pre- and post-space is stored in a dedicated register,
-centered blocks have none,
-and both use the vertical spacing register for
-non-displayed text,
-.NR ($v .
+while centered blocks have none;
+both use the vertical spacing register for
+normal text,
+.NR (tv
+[120].
 .TL
 .b .(l
 .i A
@@ -1005,13 +1008,11 @@ are suppressed.
 Emit index
 .i X
 [\c
-.b x ].
-The index is formatted in the font, size, and so forth
-.\" but not the vertical spacing--$V is used
-in effect at the time
-.b .xp
-is called,
-not those of the entries when they were collected.
+.b x ]
+using the current font style and type size
+with display vertical spacing
+(\c
+.NR (dv ).
 .sh 1 "Columnated Output"
 .TL
 .b .2c
@@ -1068,18 +1069,8 @@ only if necessary.
 Set the type size to
 .i \(+-p
 [10p],
-and the vertical spacing proportionally.
-The vertical spacing as a percentage of the type size
-is stored in
-.NR ($v
-[120].
-The percentage used internally
-by displays and annotations
-is stored in
-.NR ($V
-[120]
-(although this is not used by
-.b .sz ).
+and the vertical spacing proportionally
+(see section \[lq]Displays\[rq] above).
 This size is
 .i not
 persistent beyond most \*(ME macro calls:
@@ -2138,7 +2129,6 @@ and a square \(sq marks \*G extensions.
 \&.$6  M\(dg   pre-section heading depth 6 hook
 \&.$C  M\(dg   post-chapter title heading hook
 \&.$H  M\(dg   page/column heading hook
-\en($V R\(sq   vertical spacing of displayed text (%)
 \en($c R       current column number
 \&.$c  M\(dd   output chapter number and title
 \en($d R       delayed text number
@@ -2153,7 +2143,6 @@ and a square \(sq marks \*G extensions.
 \&.$p  M\(dd   output section heading
 \en($s R       column spacing (indentation)
 \&.$s  M\(dd   output footnote area separator
-\en($v R\(sq   vertical spacing of text (%)
 \e%    F\(sc   control hyphenation
 \en%   R\(sc   current page number
 \e&    F\(sc   non-printing input break
@@ -2234,6 +2223,7 @@ and a square \(sq marks \*G extensions.
 \en(df R       display font
 \&.do  M\(sc\(sq       operate with compatibility mode off
 \&.ds  M\(sc   define string
+\en(dv R\(sq   vertical spacing of displayed text (%)
 \en(dw R\(sc   day of the week
 \e*(dw S       weekday name
 \en(dy R\(sc   day of the month
@@ -2347,6 +2337,7 @@ and a square \(sq marks \*G extensions.
 \&.tp  M       begin title page
 \en(tp R       title type size in points
 \&.tr  M\(sc   translate characters
+\en(tv R\(sq   vertical spacing of text (%)
 \&.u   M       underline argument
 \&.uh  M       begin unnumbered section
 \&.ul  M\(sc   underline output lines
diff --git a/tmac/e.tmac b/tmac/e.tmac
index 2c267881..2a6b0a65 100644
--- a/tmac/e.tmac
+++ b/tmac/e.tmac
@@ -327,15 +327,15 @@
 .if (\\n(_w<=\\n($l)&(\\n(?W=0) \
 \{\
 .      \" Compute fudge factor (must be < 1P).
-.      nr _b (\\n(ppp*\\n($vu)/200u
-.      if \\n(_bu>((\\n(bmu-\\n(fmu-((\\n(tpp*\\n($vu)/100u))/2u) \
-.              nr _b (\\n(ppp*\\n($vu)/100u-\n(.Vu
+.      nr _b (\\n(ppp*\\n(tvu)/200u
+.      if \\n(_bu>((\\n(bmu-\\n(fmu-((\\n(tpp*\\n(tvu)/100u))/2u) \
+.              nr _b (\\n(ppp*\\n(tvu)/100u-\n(.Vu
 .      nr _b +\\n(bmu
 .\}
 .nr _B \\n(_bu
 .ch @f
 .wh -\\n(_bu @f
-.nr _b +(\\n(ppp*\\n($vu)/100u \" add 1 paragraph v in case sweep past
+.nr _b +(\\n(ppp*\\n(tvu)/100u \" add 1 paragraph v in case sweep past
 .if \n@>2 .tm @n .p=\\n(.p bm=\\n(bm _b=\\n(_b _B=\\n(_B
 .nr ?f 0                       \" reset footnote flag
 .if \\n(?o \
@@ -445,7 +445,7 @@
 .@O \\n(_ou
 .rs
 .\" Move to footer position.
-.sp |\\n(.pu-\\n(fmu-((\\n(tpp*\\n($vu)/100u)
+.sp |\\n(.pu-\\n(fmu-((\\n(tpp*\\n(tvu)/100u)
 .@t $f\"                       \" output footer title
 .nr ?h 0
 .bp
@@ -939,7 +939,7 @@
 .ie !"\\$1\\$2"" \
 \{\
 .      sp \\n(ssu              \" one of them is non-null
-.      ne \\n(.Lv+\\n(.Vu+\\n(psu+((\\n(spp*\\n($vu*\\n(.Lu)/100u)
+.      ne \\n(.Lv+\\n(.Vu+\\n(psu+((\\n(spp*\\n(tvu*\\n(.Lu)/100u)
 .      \" exdent if \\$3 > 0
 .      ie 0\\$3 \
 .              ti -(\\n(siu-\\n(sou)
@@ -1009,7 +1009,7 @@
 .if \n@>4 .tm -- )z << @), .z=\n(.z
 .rr _0
 .if !\\n(?b \
-.      nr dn +(\\n(ppp*\\n($vu)/200u+\\n(zsu
+.      nr dn +(\\n(ppp*\\n(tvu)/200u+\\n(zsu
 .nr dl -\n(.H          \" fudge factor necessary to make it work
 .ie ((\\n(dn+\n(.V)>=\\n(.t):(\\n(?a):((\\n(dl>\\n($l)&(\\n($c>1)) \
 \{\
@@ -1103,7 +1103,7 @@
 .@C 1
 .@F \\n(df
 .if \\n($R .@V
-.vs \\n(.sp*\\n($Vu/100u
+.vs \\n(.sp*\\n(dvu/100u
 .nf
 .if "\\*(|p"F" \
 .      fi                      \" set fill mode if "F" parameter
@@ -1483,15 +1483,15 @@
 .de sz                 \" *** set point size and vertical spacing
 .ps \\$1
 .if \\n($r .@v
-.vs \\n(.sp*\\n($vu/100u       \" default vs at pointsize + 20%
+.vs \\n(.sp*\\n(tvu/100u       \" default vs at pointsize + 20%
 ..
 .
-.de @v                 \" --- possibly set $v from $r
-.if (1i>=240u)&(1p<=\\n($r)&(\\n($r<=4p) .nr $v \\n($r00/1p
+.de @v                 \" --- possibly set tv from $r
+.if (1i>=240u)&(1p<=\\n($r)&(\\n($r<=4p) .nr tv \\n($r00/1p
 ..
 .
-.de @V                 \" --- possibly set $V from $R
-.if (1i>=240u)&(1p<=\\n($R)&(\\n($R<=4p) .nr $V \\n($R00/1p
+.de @V                 \" --- possibly set dv from $R
+.if (1i>=240u)&(1p<=\\n($R)&(\\n($R<=4p) .nr dv \\n($R00/1p
 ..
 .
 .de @E         \" --- store in _F argument to \f for restoring font
@@ -1593,7 +1593,7 @@
 .      xl \\n($lu-\\n(fuu
 .      @F \\n(ff
 .      sz \\n(fp
-.      vs \\n(.sp*\\n($Vu/100u
+.      vs \\n(.sp*\\n(dvu/100u
 .      if !\\n(?f \
 \{\
 .              nr _b +1v       \" allow space for $s
@@ -1612,7 +1612,7 @@
 .              xl \\n($lu-\\n(fuu
 .              @F \\n(ff
 .              sz \\n(fp
-.              vs \\n(.sp*\\n($Vu/100u
+.              vs \\n(.sp*\\n(dvu/100u
 .              if !\\n(?f \
 .                      $s
 .              br
@@ -1633,7 +1633,7 @@
 .      xl \\n($lu-\\n(fuu
 .      @F \\n(ff
 .      sz \\n(fp
-.      vs \\n(.sp*\\n($Vu/100u
+.      vs \\n(.sp*\\n(dvu/100u
 .      fi
 \!.(f \\$1
 \!.@N
@@ -1691,11 +1691,11 @@
 .de (d                 \" *** begin delayed text
 .am |d )d
 .sp \\n(bsu
-.vs \\n(.sp*\\n($Vu/100u
+.vs \\n(.sp*\\n(dvu/100u
 ..
 .
 .de )d                 \" *** end delayed text
-.vs \\n(.sp*\\n($vu/100u
+.vs \\n(.sp*\\n(tvu/100u
 .nr $d +1
 ..
 .
@@ -1766,7 +1766,7 @@
 .br
 .@C 2
 .ls 1
-.vs \\n(.sp*\\n($Vu/100u
+.vs \\n(.sp*\\n(dvu/100u
 .fi
 .in +\\n(piu
 .ds |X x
@@ -1997,8 +1997,14 @@
 .\"            *** PARAMETRIC INITIALIZATIONS ***
 .
 .
-.nr $v \n(.v00+\n(.sp-1/\n(.sp \" vs as % of ps for .sz request
-.nr $V \n($v                   \" same for displays & footnotes
+.\" In groff 1.23, we keep $v and $V to maintain 30 years of continuity,
+.\" but expose new names `tv` and `dv`, respectively, making it more
+.\" obvious that user alteration of these register values is supported.
+.\" See discussion of `$R` and `$r` below.
+.nr tv \n(.v00+\n(.sp-1/\n(.sp \" vs as % of ps for .sz request
+.nr dv \n(tv                   \" same for displays & footnotes
+.do aln $v tv
+.do aln $V dv
 .nr hm 4v                      \" header margin
 .nr tm 7v                      \" top margin
 .nr bm 6v                      \" bottom margin
@@ -2089,9 +2095,21 @@
 .@R $0\"               \" section depth
 .@R $i\"               \" paragraph base indent
 .@R $p\"               \" numbered paragraph number
-.\" $r and $R are legacy BSD document support, undocumented in groff.
-.@R $r\"               \" ratio of vs to ps (may override $v)
-.@R $R\"               \" same for displays (may override $V)
+.\" [Before groff 1.06] the groff -me macros treated the $r and $R
+.\" number registers in a way that was incompatible with the BSD -me
+.\" macros.  The reason for this was that the approach used by the BSD
+.\" -me macros does not work with low resolution devices such as -TX75
+.\" and -TX100.  However, this caused problems with existing -me
+.\" documents.  In [groff 1.06], the vertical spacing is controlled by
+.\" the $v and $V registers which have the same meaning as $r and $R in
+.\" earlier groff releases.  In addition, if the $r or $R register is
+.\" set to a value that would be correct for the BSD -me macros and a
+.\" low resolution device is not being used, then an appropriate value
+.\" for the $v or $V register is derived from the $r or $R register.
+.\"
+.\" Thirty years later, we rename `$v` to `tv` and `$V` to `dv`.
+.@R $r\"               \" ratio of vs to ps (may override tv)
+.@R $R\"               \" same for displays (may override dv)
 .@R df\"               \" display font: same as surrounding text
 .@R so\"               \" additional section title offset
 .@R fu\"               \" footnote undent