bugGNU roff - Bugs: bug #61632, [me] delayed text numbering...

 
 

bug #61632: [me] delayed text numbering doesn't seem to quite work

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Tue 07 Dec 2021 01:56:19 PM UTC
   
 
Category:  Macro package me Severity:  3 - Normal
Item Group:  Incorrect behaviour Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Tue 14 Dec 2021 06:27:18 AM UTC, comment #2: 


commit 1ed0b9f52e9f8e44bc992e4cad4fa77a6021e4d8
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Wed Dec 8 01:18:32 2021 +1100

    [me]: Fix automatic numbering of delayed text.

    * tmac/e.tmac: Fix automatic numbering of delayed text.

      (initialization, pd): Remove unused auto-incrementation from
      `$d` delayed text number register.

      (initialization, pd): Remove auto-incrementation from `$d` delayed
      text number register.

      ()d): Increment `$d` register unconditionally, no longer conditionally
      on whether the delayed text marker string `#` has been interpolated.

      ()d, pd): Update `#` string using new `_#` string.  Stop
      initializing the string with `\k` mark-setting escape sequence.

    * doc/meref.me (Annotations) <)d>: Document now-unconditional
      incrementation of `$d` register.

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


G. Branden Robinson <gbranden>
Group administrator
Fri 10 Dec 2021 03:18:17 AM UTC, comment #1: 

Ah, like all wizards, Allman was subtle.

The `*` string is defined differently based on whether you're inside the footnote or outside of it, because he expects you to interpolate it again if you're using automatic numbering.

Populating a register with the horizontal mark escape sequence looks way more elegant now, since if you have to redefine the string inside the footnote diversion anyway, you can take that out.  You can also make the footnote number robust to repeated interpolation inside the footnote text (though that doesn't seem a property that would get much use).  Anyway, an auto-incrementing register really isn't the best tool for this problem.

I'm continuing to study this to see how parallel I can make delayed text and footnotes.  I might end up not changing footnotes at all.

G. Branden Robinson <gbranden>
Group administrator
Tue 07 Dec 2021 01:56:19 PM UTC, original submission:  

The "delayed text" feature of me(7) has a somewhat mysterious name but really it seems to be almost ideal for endnotes.

Or it would be if it didn't have a bug that prevents incrementation of the note numbers before the first emission of delayed texts (endnotes).

Input:

$ cat delayed.me
.pp
paragraph 1
.(d
\*# foo
.)d
.(d
\*# bar
.)d
.pd
.(d
\*# baz
.)d
.pp
paragraph 2
.(d
\*# qux
.)d
.pd
.pp
paragraph 3


Heirloom Doctools troff output (e.tmac 2.14):


$ ./bin/nroff -me ./delayed.me |cat -s

     paragraph 1

[1] foo

[1] bar

     paragraph 2

[1] baz

[2] qux

     paragraph 3


(I've snipped extra lines at the end; for some reason this version of me(7) emits invisible [backspaced-over] garbage, and this fools "cat -s".  This doesn't affect later versions of me(7) so I'll spend no more time on it.)

groff 1.22.4 me(7) output:


$ nroff -me EXPERIMENTS/delayed.me | cat -s

     paragraph 1

[1] foo

[1] bar

     paragraph 2

[1] baz

[2] qux

     paragraph 3


Root-cause analysis: Allman appears to nowhere interpolate auto-incrementing registers in e.tmac such that the incrementation will apply (see e.tmac 8.1 from 4.4BSD), despite their obvious utility for things like the .sh section number components and footnote numbers.  Maybe the feature was broken in the troff available to him.

Instead, what he does is set a mark register with `\k`: '#' for delayed text and '*' for footnotes, and embeds this in string definitions of the same name which also interpolate the footnote/delayed text number.  The mark is never set if the string is never emitted, which I think explains some curious language in {me,}ref.me about how these numbers are incremented if they've been "referenced".

But even this does not work in the case of delayed text, as seen above.  Only after `.pd` has been called the first time does the incrementation occur.

Here's what happens at initialization:


.nr $d 1 1                      \" delayed text number
.ds # [1]\k#\"                  \" delayed text "name"


An auto-incrementing register `$d` is set up, but it is never interpolated with `\n+($d`.

The `#` string is defined, and if it is ever interpolated, the horizontal position will be stored in register `#`.

Here are the macros that start, end, and emit delayed text.


.de (d                  \" *** begin delayed text
.am |d )d
.sp \\n(bsu
..
.
.de )d                  \" *** end delayed text
.if \\n# \
.       nr $d +1
.ds # [\\n($d]\k#
.rr #
..
.
.de pd                  \" *** print delayed text
.|d
.rm |d
.nr $d 1 1
.ds # [1]\k#
..


Notice how in the delayed-text-closing macro `)d`, the `#` string is defined again...but it still hasn't been interpolated.

One could argue that this was a deliberate design choice, that Allman meant for people to be able to accumulate a single "item", in some sense, of delayed text in stages...but this approach would only work for the first batch of delayed texts, say for the first chapter.  When those are emitted, the `#` string is interpolated and the `#` register comes to know sin (is assigned a nonzero value).  (Observe that the `#` register is never modified except by further interpolations of the `#` string.)  Moreover, there's an easier way to achieve that effect: simply don't interpolate the `#` string inside the delayed text except when you want it, and/or manage the value of the `$d` register yourself.  Both are documented in the reference manual and extend an invitation thus.

To me this seems like unintended behavior arising from failure to leverage auto-incrementing registers.

One might wonder why footnotes don't exhibit the same problem.  Observe that there is no `pf` macro counterpart to `pd`.  Footnotes, being at the foot of the page, don't rely on the user to call a macro to emit then; this is handled automatically by me(7)--though an enterprising user can defeat it, of course, by clobbering package internals.

I have a fix in preparation.  Here is the output.


$ nroff -M./tmac -me EXPERIMENTS/delayed.me | cat -s
     paragraph 1

[1] foo

[2] bar

     paragraph 2

[1] baz

[2] qux

     paragraph 3


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 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 3 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

    Back to the top

    Powered by Savane 3.13-caa5.
    Corresponding source code