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

[Dave]

URL:
  <https://savannah.gnu.org/bugs/?57944>

                 Summary: doc/groff.texi: expand .de documentation
                 Project: GNU troff
            Submitted by: barx
            Submitted on: Tue 03 Mar 2020 04:53:18 AM CST
                Category: Core
                Severity: 3 - Normal
              Item Group: Documentation
                  Status: None
                 Privacy: Public
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any
         Planned Release: None

    _______________________________________________________

Details:

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.




    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?57944>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/