bugGNU troff - Bugs: bug #60479, tmac/e.tmac-u is missing .PF macro...


bug #60479: tmac/e.tmac-u is missing .PF macro documented in doc/meref.me

Submitted by:  Dave <barx>
Submitted on:  Thu 29 Apr 2021 02:49:20 PM UTC  
Category:  Macro - me Severity:  3 - Normal
Item Group:  Incorrect behaviour Status:  None
Privacy:  Public Assigned to:  None
Open/Closed:  Open Planned Release:  None

Add a New Comment (Rich Markup)

You are not logged in

Please log in, so followups can be emailed to you.


Wed 05 May 2021 06:41:25 AM UTC, comment #5: 

comment #3:

> .GF also omits an HTML check that .GE includes, which
> honestly to me looks like it creates a bug if someone uses
> a .GS and .GF pair with HTML output.

Also now its own bug report!  Bug #60526.

Dave <barx>
Project Member
Mon 03 May 2021 08:15:30 AM UTC, comment #4: 

comment #1:

> Although even pic's own man page (src/preproc/pic/pic.1.man)
> doesn't mention the fact, pic itself recognizes .PF (as well
> as .PE, which is documented) as an end marker for pic blocks

Ah.  If you dig deep enough, .PF is documented: it's in doc/pic.ms, which also notes that the F stands for "flyback," shedding a little light on one of the mysteries in bug #60478.

Bug #60504 now addresses this omission in the man page.

Dave <barx>
Project Member
Fri 30 Apr 2021 11:26:03 PM UTC, comment #3: 

It appears a .PF for -me is not even that hard to implement.  As a first crack, I tried simply:

.als PF PE

(Worth noting: the source code for .IE and .IF are identical, though one is not defined as an alias of the other, likely because .als is a groff extension and much -me code predates groff.)

This seems to do basically what I expect.  With that definition, running this code through "groff -p -me":

Hello, world.

produces a horizontally centered circle with "Hello, world" below it, flush left.  Then changing the .PE to a .PF produces the same circle but with the "Hello, world" aligned with its top, still flush left.  So pic does the actual work of figuring out where to leave the cursor upon exit; e.tmac need only recognize .PF as a valid macro.

I think this alias is a simple but functional solution to the problem.

But there is probably more refinement that could be done.  For instance, .GE and .GF are not identical, and one of the differences between them is that .GE includes a ".sp .6" that .GF does not.  The existing .PE likewise includes a ".sp .6", and probably a better .PF would omit this.

(.GF also omits an HTML check that .GE includes, which honestly to me looks like it creates a bug if someone uses a .GS and .GF pair with HTML output.  But that is another issue for another day.)

Thus, were I to make .PE and .PF resemble .GE and .GF, sans probable bug, I would write them as follows:

.de PE                  \" *** end pic picture
.sp .6
.de PF                  \" *** end pic picture; stay at top
.if \\n(?n .PS_nm_check resume
.if \\n(g7 .fi

These two definitions would replace the current PE definition; functionally, the old and new are identical.

As I've said before, I mostly don't understand the code in tmac/e.tmac-u, so both the above possible solutions--which both amount to some degree of copying code I don't understand--could have problems.

However, I think having a potentially problematic .PF is better than having none at all.  And since either change involves only creating a new macro (one involves refactoring but not altering an existing one), either solution should be safe from causing regressions.

(Either proposal above would also need an accompanying change to the -me manual, documenting .PF in Section 9.)

Any opinions/preferences between these two, or suggestions for further refinements?  I'm happy to write a patch for either one.

Dave <barx>
Project Member
Thu 29 Apr 2021 07:35:57 PM UTC, comment #2: 

comment #1:

> pic itself recognizes .PF (as well as .PE, which is documented) as an end marker for pic blocks:

In further fact:

  • GNU's pic has recognized both end macros since earliest days: starting on line 82 of commit 351da0dc of pic/main.c, you can see that pic sets the variable flyback_flag to false for .PE and true for .PF.  Though this file has since been renamed to src/preproc/pic/main.cpp, this segment of code remains unchanged from that original 1991 commit.
  • Heirloom's pic does not recognize .PF as an end marker, suggesting it was never supported under historical implementations (since Heirloom generally only adds functionality).

$ heirloom-pic pictest > /dev/null
heirloom-pic: syntax error near pictest:4
context is
        This is >>>   <<< invalid pic code.
$ sed s/PF/PE/ pictest | heirloom-pic > /dev/null

Dave <barx>
Project Member
Thu 29 Apr 2021 06:23:22 PM UTC, comment #1: 

The discrepancy between Section 9 and the Summary exists in the oldest available version of the file in groff's repository, commit 351da0dc of doc/meref.me.

The discrepancy between the documentation and the code exists in the oldest versions of both files, the above meref.me and the corresponding commit 351da0dc of macros/tmac.e (the original name of the file now called tmac/e.tmac-u).

Although even pic's own man page (src/preproc/pic/pic.1.man) doesn't mention the fact, pic itself recognizes .PF (as well as .PE, which is documented) as an end marker for pic blocks:

$ cat pictest
x = 3
This is invalid pic code.
$ pic pictest > /dev/null
$ # Now swap lines 3 and 4 of input:
$ sed -n '1,2p;  3{h;n;p;x;p}' pictest | pic > /dev/null
pic:<standard input>:3: syntax error before 'is'
pic:<standard input>:3: giving up on this picture

Dave <barx>
Project Member
Thu 29 Apr 2021 02:49:20 PM UTC, original submission:  

The Summary section of doc/meref.me documents the following six macros for use with three preprocessors:

  .GE   end gremlin picture
  .GF   end gremlin picture (with flyback)
  .IE   end ideal picture
  .IF   end ideal picture (with flyback)
  .PE   end pic picture
  .PF   end pic picture (with flyback)

However, tmac/e.tmac-u defines only five of these macros, all but PF.  Ending a pic block in a -me file with .PF thus results in the warning:

  troff: warning: macro 'PF' not defined

On the other hand, Section 9 (Preprocessor Support) of meref.me also omits .PF, documenting only the other 5 of these 6 ending macros.  This suggests that perhaps .PF was not intended to exist, and its presence in the Summary was merely copy/paste run amok.

But should there be a .PF macro?  Bug #60478 points out that the difference between .GE and .GF is where the cursor is left, and conjectures that the difference between .IE and .IF is the same.  It seems like it might be useful to make the same distinction for how to end a pic segment.  But I know nothing about how pic works, so can't evaluate whether this makes sense.

Dave <barx>
Project Member


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

Attach Files:

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 (Submitted the item)

    Do you think this task is very important?
    If so, you can add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.




    No changes have been made to this item

    Back to the top

    Powered by Savane 3.6