groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [bug #59573] typesetting.mom: traps are not initialised (set, plante


From: G. Branden Robinson
Subject: Re: [bug #59573] typesetting.mom: traps are not initialised (set, planted)
Date: Sun, 6 Dec 2020 02:58:22 +1100
User-agent: NeoMutt/20180716

[redirecting to groff@ for discussion]

Background: In https://savannah.gnu.org/bugs/index.php?59573, Bjarni
pointed out that a recent change I made caused some diagnostics to
appear.

>   GROFF    contrib/mom/examples/typesetting.pdf
> troff: ../contrib/mom/examples/typesetting.mom:638: error: cannot move
> unplanted trap macro 'FOOTER'

> troff: ../contrib/mom/examples/typesetting.mom:638: error: cannot move
> unplanted trap macro 'FN_OVERFLOW_TRAP'

>   Setting the named traps has been overlooked.

> Code in line 638:

> .if '\*[.T]'pdf' .PDF_IMAGE penguin.pdf 81p 96p

This arose from the following commit that I made after doing a lot of
experimentation with traps in an effort to learn the feature well enough
to improve our documentation of it.

commit e3b909eda11419daaf9e1ff028defc0e972ac827
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Nov 17 21:23:37 2020 +1100

    src/roff/troff/div.cpp: Error on meaningless .ch.
    
    * src/roff/troff/div.cpp (top_level_diversion::change_trap): Emit error
      diagnostic if an attempt is made to move an unplanted macro.  This
      could have been a warning, as it's pretty harmless (though possibly a
      big surprise to anyone who was wondering why their .ch was a no-op),
      but there's no good warning category for this kind of problem and I am
      not about to start a bike shed discussion about it right now.

I then asked Peter to comment since it was his usage that provoked the
diagnostics, possibly exposing our different expectations.

At 2020-11-30T15:43:26-0500, Peter Schaffter wrote:
> Follow-up Comment #2, bug #59573 (project groff):
> 
> Until now, the exhibited behaviour of groff, if not the intended
> behaviour, was to ignore .ch requests for non-existent traps.  The
> file typesetting.mom demonstrates bare-metal typesetting, so the
> FOOTER and FN_OVERFLOW traps, which are only used if START has been
> invoked (full document processing), are never set.  This has allowed
> PDF_IMAGE conveniently to process all pdf images inside the FLOAT
> mechanism, which necessarily .ch's the aforementioned traps if they
> exist and does nothing if they do not, as is the case with
> typesetting.mom.
> 
> It is simple enough to amend the PDF_IMAGE macro to invoke FLOAT only
> if START has been invoked, thus eliminating the .ch operations on
> non-existent traps, but before I do, I'd like to know the rationale
> behind the change to what, from my perspective as a macro developer,
> breaks established groff behaviour.

That's a fair criticism.  I considered the possibility that someone
might deliberately call .ch on an unplanted macro, availing themselves
of the no-op behavior, letting the surrounding logic behave as a
conditional.

It is reasonable to say that the *roff tradition of blithely treating
nonsense input quietly as a no-op, despite a documented record of
success, runs against the grain of my own habits as a programmer.

There are many requests in the *roff language that are effectively
aliases of the empty request if they're not given any arguments, or
their arguments don't make any sense, as in the instant case, but this
isn't a hard rule; sometimes invoking a request with no arguments
changes the state of the formatter (often returning something to a
defqault), and sometimes invoking a request with bad arguments provokes
complaints.

As noted in my commit message, I thought--admittedly based on little but
my own instincts and meager experience as a *roff author compared to
you--that it would be more helpful to aler the user when they were doing
something that "looked like" it should do some work, but didn't really.

Around the time of the above commit, I added the following example to
our Texinfo manual.

        .de T
        Trap sprung at \\n(nlu.
        .br
        ..
        .wh 1i T
        .wh 2i T
        foo
        .sp 11i
        .bp
        .ch T 4i
        bar
        .sp 11i
        .bp
        .ch T 5i
        baz
        .sp 11i
        .bp
        .wh 5i
        .ch T 6i
        qux
        .sp 11i

If I typoed one of the above .ch requests, perhaps saying

        .ch t 6i

having allowed the shift key to slip away from me, I'd want to know
about it.  Prior to my commit there was no way to find this out, short
of wrapping or replacing .ch itself.

What approach best suits the user base?

        1. Revert the change, possibly telling users in the manual how
        write their own validity-testing wrapper for .ch.

        2. Postpone the change for after the 1.23.0 release but advise
        of it in the release notes as planned subsequently, so people
        have time to adapt.

        3. Downgrade the error to a warning.  This will require
        determine an appropriate warning category for it.  None of the
        existing ones seems like a good fit; this is a recurring pain
        point for us.  If pressed, I would propose broadening the
        semantics of the "missing" category to rope to include arguments
        that are not simply syntactically absent but also missing after
        one level of dereference, so to speak.  I'm not altogether happy
        with the gymnastics here.  Maybe someone else has a better idea.

        4. Keep it in case my change finds a better exponent than I.  :)

Perhaps there is a #5 and so on.

What do people think?

Regards,
Branden

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]