Re: grog doesn't detect files that contain .so

[Eli Zaretskii]

> Date: Thu, 29 Jun 2017 19:39:40 +0200
> From: Ingo Schwarze <address@hidden>
> Cc: address@hidden
> 
> > But running 'grog' on it produces this:
> > 
> >   groff pdftexi2dvi.1
> > 
> > which omits the crucial -man switch.  Running 'grog' on texi2dvi.1
> > does produce the correct command.  So it sounds like 'grog' doesn't
> > include the file mentioned on the .so line?
> 
> The grog(1) script is an absolutely terrible hack - an ad-hoc
> parser parsing languages it doesn't really understand - and it
> is already excessively complicated as it stands, but at least
> it is not so crazy that it tries to completely reimplement troff.
> 
> As one example, it does *recognize* the roff .so request and adds
> the -s option to the suggested groff command line when .so occurs
> in a file that also looks like needing another preprocessor, but
> it does not *implement* the .so request, which would be needed
> to read and analyze the referenced file.
> 
> It is well-known that grog(1) cannot be perfect and sometimes
> suggests command lines that are just wrong.  So do not use it
> for any serious work.

If 'grog' is such a terrible hack, may I suggest to at least hint at
that in the documentation, and perhaps even remove it from the Groff
package?  There's nothing I could find in the current documentation
that contains even a shred of a hint in that direction.  The 'grog'
man page doesn't even have a BUGS section, but it does say that
'groffer' heavily depends on 'grog' doing TRT.

Given all this, how should a casual user of Groff succeed in guessing
that 'grog' is something to stay away of?

> > The reason I need this to work is that I have a script to format man
> > pages which runs 'grog' and then executes the command it produces.
> 
> What a terrible idea.  Don't do that.

Given the documentation, it should seem a very good idea.  And it
works very well for me in practice, except with these .so man pages.

> It is likely to result both in running unintended and not running
> required preprocessors, both resulting in misformattings.

Then why are you distributing such a buggy utility?

> Instead, make sure the manual pages contain the correct annotations,
> such that your man(1) implementation can choose the right preprocessors
> in a deterministic way rather than having a hack like grog(1) do
> some heuristic, unreliable guessing.

The problem is not with 'man'.  I use this script when I need to
produce formatted man pages in a batch job, usually when I prepare a
binary package for people who don't necessarily have Groff installed;
formatted man pages can be viewed with any text browser, like Less.

Anyway, thanks for confirming my fears about 'grog'.  Is there any
similar (but working) utility anywhere that you can recommend?