Re: Wanted: testers for heavily revised grog(1)

[G. Branden Robinson]

At 2021-06-30T13:29:09+0200, Ingo Schwarze wrote:
> G. Branden Robinson wrote on Wed, Jun 30, 2021 at 08:15:47PM +1000:
> 
> > Since we've dropped groffer from the forthcoming groff release, I expect
> > we'll be advising people more to use grog to help them figure out groff
> > command lines, and so the quality of its implementation is important
> > ("now more than ever", as U.S. politicians like to say).
> 
> My conclusion would be just the opposite.

Alas for the work I just did, then!  :P

> I think we should advise people to use groff(1), not grog(1).  You
> know, groff(1) already is a wrapper, and wrapping another wrapper
> around a wrapper is almost invariably a terrible idea.

I think you have a misconception about what grog _is_.  It's a heuristic
inference tool to help the user figure out the details of the command
line they need to type to get a roff document formatted comprehensibly.

grog's only a "wrapper" if you call its "--run" option.  If support for
that option were wholly removed, we'd shorten the 2,100-line script by
about a dozen lines.

Let's pretend groff(1) didn't exist, either.  Relatively little about
grog(1) would need to change; we'd port over or recreate the hard-coded
knowledge groff(1) has about the order preprocessors need to run in[1],
and it would output a pipeline instead of a simple command.

Helping users who are not roff experts figure out the correct invocation
ritual is a useful thing which is why, I think, Kernighan and Plauger
made it a practical example in _Software Tools_.

Would you also get rid of file(1)?  If grog's output looked like...

foobar.me: roff document, using the 'me' macro package, and requiring
  the 'pic' and 'eqn' preprocessors

...instead of just handing you a Unix command to run, it would be
precisely analogous.

> When people feel an itch to do that, it often indicates that the user
> interface wasn't well-designed in the first place.  I'd go as far as
> to claim that even the presence of a *single* wrapper (on this case,
> groff) is already an indication of weak user interface design.

True, people can always write their documents in a GUI word processor...

GNU roff's mission is to reimplement a useful and formerly proprietary
subset of AT&T Unix.  While it would be interesting to deconstruct the
wisdom of AT&T troff's architecture, I don't think such an enterprise is
within the scope of this discussion list.

> Wrappers around wrappers are at best a crutch to work around badly
> botched design, but a terrible one because they cause gratuitious
> complexity.  Complexity is bad because it forces the user to learn
> more, makes the behaviour of the software less predictable, and it
> breeds bugs - and maintenance nightmares.

There is an amount of irreducible complexity in typesetting.  mandoc(1)
only has to worry about two macro packages, two or three preprocessors
at most, and you've repeatedly indicated that only two output formats
receive any of your attention: overstriking terminals and HTML.

The GNU roff project's scope is much broader.

> If i were the only maintainer of groff, i would simply delete grog,
> too.
> 
> But i'm sure other developers disagree, so i'm happy to completely
> ignore it.  I'll certainly never use it myself for anything, i'll
> not look at bug reports concerning it, and i'll not look at patches
> proposed for it or committed to it.  Should it ever cause serious
> security vilnerabilities that aren't fixed in a timely manner, i
> might just delete it from the OpenBSD port even if it remains in
> upstream groff.
> 
> Either way, please let us not recommend the use of grog(1).

As people have probably gathered from scattered comments I've made on
Savannah and in commit messages, I have not been impressed with the code
quality of grog.pl, despite my own lack of mastery of Perl.
Nevertheless I think I have improved it (largely by replacing about a
third of it with simpler ways to accomplish its internal goals), but
significant warts remain.  So I am aware of the cost side of the
cost/benefit trade-off in its case.

A sufficient variety of macro packages and preprocessors is extant that
it is unreasonable to expect a user to manually search the configuration
space to obtain the correct incantation for the formatter (or a
pipeline).  Only the most polite roff documents supply a comment at the
top telling the user how they expect to be formatted, and Makefiles to
perform the same job have a tendency to get separated and lost.

Maybe the day will arrive when almost everyone prefers to ask
StackOverflow how to format a roff document instead of using a tool to
do so.  But I don't think that day is yet here, so it behooves us to
support something like grog and keep it reasonably fit for purpose.

Regards,
Branden

[1] src/roff/groff/groff.cpp:56-68

signature.asc
Description: PGP signature