bugGNU roff - Bugs: bug #61314, [PATCH] [me] clarify documentation...

 
 

bug #61314: [PATCH] [me] clarify documentation of $v and $V registers

Submitter:  Dave <barx>
Submitted:  Sat 09 Oct 2021 07:40:51 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
   

Jump to the original submission

Mon 12 Sep 2022 02:43:11 PM UTC, comment #6: 

Also worth noting is that the names of both these registers were subsequently changed; see bug #61710.

Dave <barx>
Group Member
Tue 21 Dec 2021 11:27:40 AM UTC, comment #5: 

It may be worth noting...


commit 406654a9ffc58535b0357e9d6c6a1a4722e42248
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Dec 12 11:37:57 2021 +1100

    doc/meref.me: Migrate "point size" -> "type size".

    * "Point size" remains in mnemonics for package register names.
    * Update prepositions: one is to say "_at_ a given type size" but "_in_
      11-point type".


G. Branden Robinson <gbranden>
Group administrator
Sun 31 Oct 2021 07:12:49 AM UTC, comment #4: 

comment #3:

> I'm aware--I participated. :)


I've been known to contribute to a discussion and then have no memory of it 6 months later.  But I shouldn't have assumed my own mental lapses were universal.

Dave <barx>
Group Member
Sat 30 Oct 2021 06:07:56 AM UTC, comment #3: 

Hi, Dave!

comment #2:

> comment #1:


> >     [It would be nice to say "type size" instead of "point size", but
> >     consistent usage would demand a much more intrusive change.  --GBR]


>
> Also, use of "point size" was pretty vigorously defended on the email list: see downthread of http://lists.gnu.org/archive/html/groff/2021-04/msg00037.html


I'm aware--I participated. :)

As noted there, I take Bjarni's point (no pun intended).

I perceive no crime against pedagogy if the me(7) and mom(7) documentation consistently uses and prefers "point size" (as, in fact, they appear to do).

But for documents which it has fallen to me to maintain, I see distinct advantages to "type size" in most contexts.

For those drawing up my bill of indictment, I'll go ahead and confess to three heresies, all of which I've shifted our documentation some way towards:

"number register" -> "register"[1]

"adjustment" -> "alignment", when no spaces get their widths altered

"point size" -> "type size"

I acknowledge that all of these offend traditional mnemonics for some of the oldest request names that exist: "nr", "ad", and "ps".

In all of these cases I think the benefit is worth the cost.  Locutions like "string-valued number register" are abusive of the learner's mind.

In the instant case, me(7) was written and pretty much remains in the era where the only unit used by *roff systems to reckon the type size was the point.  "Scaled points" was a groff innovation.  So the use of term is indeed less likely to occur in that context.

The bottom line is that I like consistency, but I also recognize that the domains of its application are contextual.

Regards,
Branden

[1] I have a rewrite of most of the material in our Texinfo manual on registers pending.

G. Branden Robinson <gbranden>
Group administrator
Sat 30 Oct 2021 05:51:05 AM UTC, comment #2: 

comment #1:

>     [It would be nice to say "type size" instead of "point size", but
>     consistent usage would demand a much more intrusive change.  --GBR]


Also, use of "point size" was pretty vigorously defended on the email list: see downthread of http://lists.gnu.org/archive/html/groff/2021-04/msg00037.html

Dave <barx>
Group Member
Fri 29 Oct 2021 02:39:13 AM UTC, comment #1: 


commit 342dabb0becc2fdb8688d4a1e5d961833126c061 (origin/master, origin/HEAD)
Author: Dave Kemper <saint.snit@gmail.com>
Date:   Sat Oct 9 07:40:51 2021 +0000

    doc/meref.me: Fix content nit.

    The -me Reference Manual is fairly scrupulous about documenting the
    default values of its registers, but $v and $V are two exceptions.
    [This commit] documents the default values for these (both 120).

        $ groff -me <<<'.tm \n($v \n($V'
        120 120

    There is also what I feel is an oddity in the nearby wording: "The line
    spacing as a percentage of the point size expressed in units is stored
    in \n($v."  I'm not sure what the phrase "expressed in units" is
    supposed to communicate; it's not clear whether it modifies "line
    spacing" or "point size," and neither really makes sense, even mentally
    adding the presumably intended "basic" before "units."

        $v is a percentage; if it meaningfully has a unit at all, that unit
        is %.

        In what units the point size is expressed or stored is irrelevant to
        a percentage: 120% of the point size is not dependent on the units
        expressing that point size.

    Thus this patch removes the phrase entirely.  If someone has a better
    idea what that phrase is trying to say, it could instead be reworded to
    say it more clearly.

    Fixes <https://savannah.gnu.org/bugs/index.php?61314>.

    [It would be nice to say "type size" instead of "point size", but
    consistent usage would demand a much more intrusive change.  --GBR]


G. Branden Robinson <gbranden>
Group administrator
Sat 09 Oct 2021 07:40:51 AM UTC, original submission:  

The -me Reference Manual is fairly scrupulous about documenting the default values of its registers, but $v and $V are two exceptions.  The attached patch documents the default values for these (both 120).


$ groff -me <<<'.tm \n($v \n($V'
120 120


There is also what I feel is an oddity in the nearby wording: "The line spacing as a percentage of the point size expressed in units is stored in \n($v."  I'm not sure what the phrase "expressed in units" is supposed to communicate; it's not clear whether it modifies "line spacing" or "point size," and neither really makes sense, even mentally adding the presumably intended "basic" before "units."

  • $v is a percentage; if it meaningfully has a unit at all, that unit is %.
  • In what units the point size is expressed or stored is irrelevant to a percentage: 120% of the point size is not dependent on the units expressing that point size.


Thus this patch removes the phrase entirely.  If someone has a better idea what that phrase is trying to say, it could instead be reworded to say it more clearly.

Dave <barx>
Group Member

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #52079:  meref.me.line_spacing.patch added by barx (531B - text/x-diff)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Updated the item)
  • -email is unavailable- added by barx (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
    2021-10-29 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2021-10-28 gbranden StatusNone In Progress
        Assigned toNone gbranden
    2021-10-09 barx Attached File- Added meref.me.line_spacing.patch, #52079

    Back to the top

    Powered by Savane 3.13-4448.
    Corresponding source code