bugGNU roff - Bugs: bug #58682, [me] length of footnote separator...

 
 

bug #58682: [me] length of footnote separator is not as documented

Submitter:  Dave <barx>
Submitted:  Tue 30 Jun 2020 01:02:11 PM 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

Tue 14 Dec 2021 06:26:22 AM UTC, comment #8: 

One thing led to another, and I ended up revising the entire meref.me document, from soup to nuts.

Jeez, that was a lot of work.  But now I think I understand the macro package, so hooray.



commit 3ee567bfce30afb984b0d213a97c1c543b0e525f
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Dec 7 16:30:32 2021 +1100

    [me]: Fix Savannah #58682.

    * doc/meref.me: Fix documentation error; the `$s` macro draws a
      horizontal line of 2 inches' length, not 1.5 inches.

    Fixes <https://savannah.gnu.org/bugs/?58682>.  Thanks to Dave Kemper for
    the report.


G. Branden Robinson <gbranden>
Group administrator
Sat 11 Dec 2021 11:16:25 PM UTC, comment #7: 

comment #6:

> But that is a tighter restriction than is necessary
> on the name space,


It is, but it's impossible to concisely document the available namespace, even when that space is limited to two characters.  ".mp, .np, and .op are available; .lp and .pp are not" gets clunky pretty quickly.  It's a useful simplification to say "all names fitting this pattern are available" without additionally implying "ONLY names fitting this pattern are available."  Asterisk-followed-by-alphanumeric gives 62 unique macro names for the novice user; the power user can read the code and figure out what others he can grab.

> and not an example that is modeled in Allman's own documents,
> the intro and reference manuals.


Yes, but at the time Allman was the supreme -me power user.

> Maybe he meant the `*` as a glob.


With X being defined as any alphanumeric, it's hard to imagine what * might glob for, since a lot of single-character-followed-by-an-alphanumeric identifiers are in use.

Dave <barx>
Group Member
Fri 10 Dec 2021 03:14:11 AM UTC, comment #6: 


comment #5:

> comment #4:
> > I've tried to decide this with web searches.  I get hits,
> > but they rapidly become irrelevant, probably because "me"
> > with "reference manual" just isn't distinctive enough.
>
> I was more thinking that someone searching that phrase as a title would put the whole things in quotes (which would prevent the revised title from matching), but maybe your average googler doesn't worry about such niceties.


I don't know how many people know about quoted matches.  I assume it's more than know about keyword exclusion with a prefixed `-`.

> > it looks like Allman was depositing regex syntax into his
> > explanation without warning
>
> I don't think that's how he intended .*X -- I believe that's a literal dot (technically not part of the macro name), a literal asterisk, and any letter or digit.  My reading is that the -me macro set defines no macros beginning with an asterisk, thus those names are all up for grabs in user space.


Ah, hmm.  Yes, I think you're closer.  But that is a tighter restriction than is necessary on the name space, and not an example that is modeled in Allman's own documents, the intro and reference manuals.  Maybe he meant the `*` as a glob.

In any case, it's recast away now.

> > groff me(7) users are far less restricted with respect to
> > naming their macros, thanks to the removed length limit.
>
> That's probably the key thing to point out here: any name of three or more characters is automatically safe from conflicts.  With this freedom, modern users are less likely to use potentially confusing characters like * in their macro names at all.


Yes.  I am dithering on how much to talk about compatibility mode; unlike groff's ms(7), its me(7) is written to be usable in that mode.  Or it mostly was.  I fixed some nits in that area.

G. Branden Robinson <gbranden>
Group administrator
Thu 09 Dec 2021 07:01:18 PM UTC, comment #5: 

comment #4:

> I've tried to decide this with web searches.  I get hits,
> but they rapidly become irrelevant, probably because "me"
> with "reference manual" just isn't distinctive enough.


I was more thinking that someone searching that phrase as a title would put the whole things in quotes (which would prevent the revised title from matching), but maybe your average googler doesn't worry about such niceties.

> it looks like Allman was depositing regex syntax into his
> explanation without warning


I don't think that's how he intended .*X -- I believe that's a literal dot (technically not part of the macro name), a literal asterisk, and any letter or digit.  My reading is that the -me macro set defines no macros beginning with an asterisk, thus those names are all up for grabs in user space.

> groff me(7) users are far less restricted with respect to
> naming their macros, thanks to the removed length limit.


That's probably the key thing to point out here: any name of three or more characters is automatically safe from conflicts.  With this freedom, modern users are less likely to use potentially confusing characters like * in their macro names at all.

Dave <barx>
Group Member
Thu 09 Dec 2021 04:45:04 PM UTC, comment #4: 

comment #3:

> I'm undecided about the wisdom of altering the title.  The new title is more precise.  But the document remains at heart the same one that's been around for 40-some years, time enough to acquire citations in related literature under its decades-old title.


I've tried to decide this with web searches.  I get hits, but they rapidly become irrelevant, probably because "me" with "reference manual" just isn't distinctive enough.

I may well back this out, though, except I'm pretty firmly decided on losing the leading hyphen (which will stymie most inexpert web searches anyway) and setting the package name in italics (or bold italics if the surrounding weight is already bold).

> Within the groff tree, the title (and author list, which has also changed, but that I consider uncontroversial) will need to be updated at least in groff_me(7) and (the English and French) "Writing Papers with GROFF using -me."


Acknowledged.  I thought of that but didn't actually put it on a checklist, creating a significant oversight hazard.  ;-)
 

> In the content itself, I have only two nits:
>
> * It's perhaps overkill to explicitly point out that 8/72,000 of an inch is "almost imperceptible."
> * "upper or lowercase" should be "upper- or lowercase"


I agree with both of these.  The latter I have wholly recast, since it looks like Allman was depositing regex syntax into his explanation without warning (to be fair, this language was not originally in the introduction, but in the documentation of the `lo` macro which GNU me(7) does not support), and on top of that, groff me(7) users are far less restricted with respect to naming their macros, thanks to the removed length limit.


 follow a rigid naming convention.
-The user may define registers,
-strings,
-and macros,
-provided that s/he
-uses single-character uppercase names
-or double-character names
-consisting of letters and digits,
+To avoid conflict,
+any user-defined register,
+string,
+or macro
+names should be single numerals or uppercase letters,
+or any longer sequence of letters and numerals
 with at least one uppercase letter.
-In no case should special characters
-be used in user-defined names.
-Locally defined macros
-should all be of the form
-.b .* \c
-.i X ,
-where
-.i X
-is any letter
-(upper or lowercase)
-or digit.
 .sh 1 "Paragraphing"


G. Branden Robinson <gbranden>
Group administrator
Wed 08 Dec 2021 09:24:31 PM UTC, comment #3: 

Looks great, Branden!  The changes definitely clarify the text.

I'm undecided about the wisdom of altering the title.  The new title is more precise.  But the document remains at heart the same one that's been around for 40-some years, time enough to acquire citations in related literature under its decades-old title.

Within the groff tree, the title (and author list, which has also changed, but that I consider uncontroversial) will need to be updated at least in groff_me(7) and (the English and French) "Writing Papers with GROFF using -me."

In the content itself, I have only two nits:

  • It's perhaps overkill to explicitly point out that 8/72,000 of an inch is "almost imperceptible."
  • "upper or lowercase" should be "upper- or lowercase"
Dave <barx>
Group Member
Tue 07 Dec 2021 01:38:03 AM UTC, comment #2: 

Hi Dave,

I think you're right.

Here's the oldest ref.me I could find.

https://svnweb.freebsd.org/csrg/share/doc/usd/20.meref/ref.me?view=co&revision=27100&content-type=text%2Fplain

I have a fix pending.  In fact, as you might have surmised from recent bug traffic, I got stuck to the tar baby of meref.me and have started rewriting it.  I'm attaching my work-in-progress.

A review is most welcome.

(file #52444, file #52445)

G. Branden Robinson <gbranden>
Group administrator
Mon 29 Mar 2021 07:31:38 AM UTC, comment #1: 

Version 1.1 of the macros, dating from May 1980, specify a line length of 2i:

http://svnweb.freebsd.org/csrg/share/me/tmac.orig_me?revision=151&view=markup#l773

I've not yet located a meref.me of similar vintage for comparison.

Dave <barx>
Group Member
Tue 30 Jun 2020 01:02:11 PM UTC, original submission:  

doc/meref.me says of macro .$s: "Currently it draws a 1.5i line."

This would be news to tmac/e.tmac-u, where the macro in its entirety is:


.de $s                  \" $$$ footnote separator
\l'2i'
..


This discrepancy has existed for the entirety of the git history of these files (i.e., since commit 351da0dc in June 1991), so it's hard to say whether 1.5i or 2i is canonically correct.  doc/meintro.me does not document .$s at all.

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 #52444:  meref.me added by gbranden (40KiB - text/x-troff-me)
file #52445:  meref.ps added by gbranden (82KiB - application/postscript)

 

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 10 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-12-14 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2021-12-07 gbranden Attached File- Added meref.me, #52444
        Attached File- Added meref.ps, #52445
        StatusNone In Progress
        Assigned toNone gbranden
    2021-12-07 barx Severity3 - Normal 2 - Minor
    2021-06-04 barx Summary-me macros: length of footnote separator is not as documented [me] length of footnote separator is not as documented
    2020-07-25 gbranden CategoryMacro - others/general Macro me

    Back to the top

    Powered by Savane 3.13-758e.
    Corresponding source code