bugGNU troff - Bugs: bug #57944, doc/groff.texi: expand .de...

 
 

bug #57944: doc/groff.texi: expand .de documentation

Submitted by:  Dave <barx>
Submitted on:  Tue 03 Mar 2020 10:53:18 AM UTC  
 
Category:  Core Severity:  3 - Normal
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 03 Mar 2020 10:53:18 AM UTC, original submission:  

An amazingly useful Tadziu-penned roff trick in the list archives (http://lists.gnu.org/archive/html/groff/2008-12/msg00006.html) has an implementation that exposes at least one, and maybe two, deficiencies in groff's .de documentation.

(1) .de's second parameter

The documentation doesn't fully describe what happens when the second parameter is used in .de (or other requests of its ilk).

There is one example in the entire info document that uses such a second parameter:

\# a dummy macro to avoid a warning
.de end
..
[snipped]
.  de bar end
.    nop \f[B]Hallo \\\\$1!\f[]
.  end

This example defines an empty, dummy macro .end.  The comment above this dummy macro says its only purpose is to suppress a warning.

Nowhere does the document address whether the .end macro can contain other instructions at all; and, if it can, what this implies:  Does .end immediately end the "bar" definition, and then .end is executed?  Or is the content of .end essentially appended to .bar?  Phrased differently, does .end end .bar at the moment .end begins, or at the moment .end ends?

CSTR #54 made this clear: it included the sentence (using "yy" in place of "end") "Input lines are copied in copy mode until the definition is terminated by a line beginning with .yy, whereupon the macro yy is called."  This should be added to the groff documentation.

(2) macros writing macros

The other interesting thing Tadziu's code does is define a macro (BB) to define a macro (XX).  For this it uses a syntax that would be illegal in most modern programming languages because it breaks conventional nesting.  In pseudocode, what it does is:

begin macro BB
begin macro XX
end macro BB
end macro XX

The reason it works (I assume) is that the content of macro BB is read in copy-in mode, so that "begin macro XX" isn't actually parsed until macro BB is invoked.

Arguably, since groff's info manual already documents copy-in mode, nothing further need be added to explain this.  But it's such a nonintuitive and useful way to (ab)use the language, I wonder if the manual should include an explanation or example that highlights it.

Dave <barx>

 

(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 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.5