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

 
 

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

Submitter:  Dave <barx>
Submitted:  Thu 29 Apr 2021 02:14:16 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
   

Sun 08 Aug 2021 10:01:59 AM UTC, comment #2: 


commit 1d212a1b32e85ee12f228571a990e61bee6af16a
Author: Dave Kemper <saint.snit@gmail.com>
Date:   Tue May 4 20:09:21 2021 +0000

    [me]: Improve docs of image-inclusion macros.

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


G. Branden Robinson <gbranden>
Group administrator
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>
Group 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>
Group 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 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 8 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-08-08 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2021-08-06 gbranden StatusNone In Progress
        Assigned toNone gbranden
    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.13-4448.
    Corresponding source code