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

[Ingo Schwarze]

Hi Eli,

Eli Zaretskii wrote on Thu, Jun 29, 2017 at 07:48:41PM +0300:

> If you run 'grog' on a man page that contains only a .so line, it
> fails to produce the correct Groff command needed to format the man
> page.  E.g., try this with pdftexi2dvi.1 from the Texinfo package.
> The file contains a single line:
> 
>   .so man1/texi2dvi.1

On the one hand, that is yet another reason to not use the
historical, rather fragile .so technique for manual pages
and instead use real file-system level hard or soft links,
which are much more reliable.

> 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.

> 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.  It is likely to result both
in running unintended and not running required preprocessors, both
resulting in misformattings.

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.

Yours,
  Ingo