bugGNU roff - Bugs: bug #61683, [me] either document $r and $R...

 
 

bug #61683: [me] either document $r and $R registers or rename them

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Thu 16 Dec 2021 12:48:15 AM UTC
   
 
Category:  Macro me Severity:  2 - Minor
Item Group:  Documentation Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Sat 25 Dec 2021 08:28:38 AM UTC, comment #4: 


commit 84e64beeb69a24709c85c180d9a97569c9f41099
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Mon Dec 20 22:20:08 2021 +1100

    [me]: Explain presence of undocumented registers.

    * tmac/e.tmac: Explain presence of undocumented `$r` and `$R` registers.

    Fixes <https://savannah.gnu.org/bugs/?61683>.


G. Branden Robinson <gbranden>
Group administrator
Mon 20 Dec 2021 03:12:48 AM UTC, comment #3: 

comment #1:

> original submission:
> > Or maybe someone will be able to locate a use case.
>
> If that sideways glance was in my direction, I don't have one.


Not this time.  :)

> I had never spotted this register in the source, and can't think how to use it now that I know about it.  Maybe it's some experimental dead end Eric was pursuing in the '70s that's since become ossified.
>
> On the other hand, unless you plan to repurpose the registers for something else, leaving them as-is ensures they'll continue to work for anyone who is using them but not following groff discussion channels.  I've been known to exploit undocumented -me internals on occasion to fiddle with something for which there's no approved mechanism, under the assumption that -me internals in the 21st century are largely unchanging.  Worth a code comment to note the anomalous name, but beyond that perhaps doesn't warrant a change.


I've figured out that they exist for BSD me(7) document support; I infer that Clark retained these register names deliberately.

So I will leave them.

> (If your itchy refactoring finger needs an outlet,


Maybe "inlet" is a better analogy, with as much poking around as I do...

> I'd look at the ?k register, which is set in multiple places but appears to be never used -- at least under that name, though because the language lets you build register names on the fly, a simple code examination is insufficient to determine this.)


That's true, though from what I've seen, me(7) is pretty light on dynamic symbol name construction.  It doesn't try to maintain arrays of things, for example.

I had a quick look around at `?k`.  I think it's a Boolean that answers the question "am I in a keep?".  I agree that nothing seems to ever test or interpolate it.

An example document that exercised the following types of keep or annotation, coupled with an e.tmac patched to remove all settings of the variable, and rendered with `groff -ww`, would, I think, test my hypothesis effectively.

(q, )q: long quotation
(l, )l: list
(z, )z: floating keep
(b, )b: block

G. Branden Robinson <gbranden>
Group administrator
Mon 20 Dec 2021 02:59:29 AM UTC, comment #2: 

These register names originate in BSD me(7); apparently James Clark generalized them, creating `$v` and `$V` (names that BSD me(7) does not use).

It therefore makes sense to accept them for handling of legacy documents, but not to otherwise document them at present (Clark did not add a "Differences from BSD me" section to meref.me).

A comment in the sources will serve until and unless such a section is added.

https://svnweb.freebsd.org/csrg/share/doc/usd/20.meref/ref.me?revision=67302&view=markup

G. Branden Robinson <gbranden>
Group administrator
Fri 17 Dec 2021 08:38:14 PM UTC, comment #1: 

original submission:

> Or maybe someone will be able to locate a use case.


If that sideways glance was in my direction, I don't have one.  I had never spotted this register in the source, and can't think how to use it now that I know about it.  Maybe it's some experimental dead end Eric was pursuing in the '70s that's since become ossified.

On the other hand, unless you plan to repurpose the registers for something else, leaving them as-is ensures they'll continue to work for anyone who is using them but not following groff discussion channels.  I've been known to exploit undocumented -me internals on occasion to fiddle with something for which there's no approved mechanism, under the assumption that -me internals in the 21st century are largely unchanging.  Worth a code comment to note the anomalous name, but beyond that perhaps doesn't warrant a change.

(If your itchy refactoring finger needs an outlet, I'd look at the ?k register, which is set in multiple places but appears to be never used -- at least under that name, though because the language lets you build register names on the fly, a simple code examination is insufficient to determine this.)

Dave <barx>
Group Member
Thu 16 Dec 2021 12:48:15 AM UTC, original submission:  

me(7) is pretty consistent about exposing and documenting macro, register, and string names that begin with a dollar sign.

The only exceptions I'm presently aware of (and I have looked) are `$r` and `$R`.

These are alternative ratios for vertical spacing to type size that override the (well-documented) `$v` and `$V` registers, respectively.

Here is the extent of their initialization and use in groff me(7).


  1088  .de @M                  \" --- set modes for display
  1089  .nr ?k 1
  1090  .@C 1
  1091  .@F \\n(df
  1092  .if \\n($R .@V
  1093  .vs \\n(.sp*\\n($Vu/100u
  1094  .nf
  1095  .if "\\*(|p"F" \
  1096  .       fi                      \" set fill mode if "F" parameter
  1097  .if \\n(_d=4 \
  1098  .       in 0
  1099  .if \\n(_d=3 \
  1100  \{\
  1101  .       in +\\n(biu
  1102  .       xl -\\n(biu
  1103  .\}
  1104  .if \\n(_d=1 \
  1105  .       ce 10000
  1106  ..

  1462  .\"             *** FONT AIDS ***
  1463  .
  1464  .
  1465  .de sz                  \" *** set point size and vertical spacing
  1466  .ps \\$1
  1467  .if \\n($r .@v
  1468  .vs \\n(.sp*\\n($vu/100u        \" default vs at pointsize + 20%
  1469  ..
  1470  .
  1471  .de @v                  \" --- possibly set $v from $r
  1472  .if (1i>=240u)&(1p<=\\n($r)&(\\n($r<=4p) .nr $v \\n($r00/1p
  1473  ..
  1474  .
  1475  .de @V                  \" --- possibly set $V from $R
  1476  .if (1i>=240u)&(1p<=\\n($R)&(\\n($R<=4p) .nr $V \\n($R00/1p
  1477  ..

  2067  .@R $r\"                \" ratio of vs to ps (may override $v)
  2069  .@R $R\"                \" same for displays (may override $V)


(Don't take the line numbers too literally, I'm pasting from a working tree.)

So `$r` overrides `$v` (and `$R` overrides `$V`) only if there are more than 240 basic units per inch (so, probably a typesetting device), and this ratio variable is in the range of 1 to 4 points, inclusive.

It is not at all clear to me what these registers are for and I therefore am not sure how to document them.

They are initialized to zero.  Only someone who knows about them from reading the package sources or folklore would think to set them.

I therefore propose to move them to a more private part of the name space.  As it happens, neither `_R` nor `_r` are taken.  Perhaps in groff 1.24 we can get rid of them entirely.

Or maybe someone will be able to locate a use case.

G. Branden Robinson <gbranden>
Group administrator

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by barx (Posted a comment)
  • -email is unavailable- added by gbranden (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-01-11 gbranden Item GroupNone Documentation
    2021-12-25 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2021-12-20 gbranden StatusNeed Info In Progress
        Assigned toNone gbranden

    Back to the top

    Powered by Savane 3.13-02a9.
    Corresponding source code