Re: [Groff] broken interaction between line numbering and diversions

[Peter Schaffter]

Dave --

On Wed, Sep 17, 2014, Dave Kemper wrote:
> On 9/17/14, Tadziu Hoffmann <address@hidden> wrote:
> > I think you're using the diversion wrong.
> 
> This is, admittedly, an artificial example cooked up to illustrate the
> behavior.  This is clearly a situation where a diversion, or even a
> macro, would be unnecessary at all.
> 
> The question I'm posing is whether a user who uses a diversion in this
> "wrong" (or, let's say, less than optimal) manner should see output
> that is so clearly not what was intended, or whether the software
> should do something intelligent with the user's suboptimal input,
> producing output that is probably what the user wanted.

Subjectively, I find .nm a bit clunky, as if it were implemented
as an afterthought.  Again, that's purely subjective, based on the
difficulty I had implementing a (relatively) sane line numbering
strategy for the mom macros.

That said, the real issue is the correct way to output your
line-numbered diversion, ie by preceding it with .nf.

The rules and conventions surrounding diversions are well-documented
but not all in one place.  Users have to synthesize scattered bits
and pieces of information, which is hard to do without reading all
of 'info groff' (repeatedly).  For example:

  - there is no mention of .nf in "5.25 Diversions"
  - there is no mention of diversions in "5.7 Manipulating
    Filling and Adjusting => .nf"
  - there is no mention of diversions in "5.31 Miscellaneous => .nm"

Getting groff to do "something intelligent with suboptimal input"
isn't intrinsic to its design.  The opposite, in fact: groff expects
intelligent use of optimal input.  It's a harsh and unforgiving
taskmaster, and often flouts the principle of least astonishment.
Something more lenient and less whimsical-seeming would be great,
but it wouldn't be groff.

What groff needs, more than anything else, is a new book--a sort of
updated, groff-specific UTP--that doesn't just document behaviour
but discusses real-world groff usage in depth.  "Groff for Smart
Dummies", IOW.  If I could get a contract to write such a book, I'd
take it on in a heartbeat.  (It's far more work than my free time
allows.)

> Groff is not modern software.  But should it make some concessions
> to the fact that it's still around in 2014?

Not so much concessions as accommodations.  E.g., the .ul request,
recently discussed, shouldn't be altered.  Rather, a means
to implement no-fault underlining as a new request should be
considered.

-- 
Peter Schaffter
http://www.schaffter.ca