bugGNU troff - Bugs: bug #60478, [PATCH] doc/meref.me: unclear...

 
 

bug #60478: [PATCH] doc/meref.me: unclear documentation of macros .IE, .IF, .GE, .GF

Submitted by:  Dave <barx>
Submitted on:  Thu 29 Apr 2021 02:14:16 PM UTC  
 
Category:  Macro - me Severity:  2 - Minor
Item Group:  Documentation 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.

 

Tue 04 May 2021 08:09:21 PM UTC, comment #1: 

doc/pic.ms confirms that "flyback" is Kernighanese for leaving the position at the top of the included image.

To that end, I've attached a patch to better explain this in meref.me.

This patch also updates the Summary description of .PF to match those of .GF and .IF, even though .PF's fate is in limbo until bug #60479 is resolved.

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

Section 9 (Preprocessor Support) of doc/meref.me documents four of its preprocessor ending macros thus:

  .IE        End ideal picture.
  .IF        End ideal picture (alternate form).
  .GE        End gremlin picture.
  .GF        End gremlin picture (alternate form).

No other text in this section reveals the difference between these regular and "alternate" ending macros.

This manual's Summary section is minusculely more illuminating, documenting these four macros as:

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

The word "flyback" appears nowhere else in the manual, however, so the user is still left to guess what this means.

The only other -me-specific documentation, doc/meintro.me, does not document these macros at all (unsurprisingly, given its scope).

Outside -me documentation, the src/preproc/grn/grn.1.man man page clears this up for the .GE/.GF pair: "[When .GE specifies] the end of the picture, the position on the page is the bottom of the gremlin picture. If the grn entry is ended with .GF instead of .GE, the position is left at the top of the picture."

The ideal preprocessor is not included with groff, so no other groff documentation covers .IE and .IF, but it's a reasonable guess (given the identical wording to the .GE/.GF pair) that the distinction between them is the same as for .GE and .GF.

In any case, meref.me should be less vague about the differences between these macros.

Dave <barx>
Project Member

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #51381:  meref.flyback.patch added by barx (2KiB - text/x-patch)

 

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.

     

     

     

    Follow 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-05-04 barx Attached File- => Added meref.flyback.patch, #51381
    2021-05-04 barx Severity3 - Normal => 2 - Minor
        Summarydoc/meref.me: unclear documentation of macros .IE, .IF, .GE, .GF => [PATCH] doc/meref.me: unclear documentation of macros .IE, .IF, .GE, .GF

    Back to the top


    Powered by Savane 3.6