mmroff limitations (was: Groff's -mm Indexing)

[G. Branden Robinson]

Hi Damian,

At 2023-07-01T11:51:44+1000, Damian McGuckin wrote:
> mmroff is broken. It assumes that '-mm' is the first argument to
> 'groff'

More precisely, it forces "-mm" to be the first "-m" argument.

contrib/mm/mmroff.pl:
  # mmroff should always have -mm, but not twice
  @ARGV = grep(!/^-mm$/, @ARGV);
  my $check_macro = "groff -rRef=1 -z -mm @ARGV";
  my $run_macro = "groff -mm @ARGV";

(Those variable names are poorly chosen, by the way.)

We should not just interpolate the `ARGV` list _before_ `mm` instead:
that would create a problem with the use of localization packages like
"fr.tmac".

It is a simple fact that some macro files must be loaded before others,
and mmroff is not flexible enough to support general use.

> I use '-ma4' to groff to force A4 before '-mm'.

You'll want to migrate to '-dpaper=a4'; "a4.tmac" is disappearing in
groff 1.23.0 after having been supplanted 20 years ago or so.

NEWS:
  o The "a4.tmac" file has been dropped from the distribution.  Its
    successor, "papersize.tmac", has been present and documented for
    nearly 20 years.  See subsection "Paper format" of groff(1).

> So with 'mmroff', my document comes out in 'letter'. Not quite what I
> want

For the _immediate_ problem, -dpaper will save you, because it is
(indirectly) handled by troffrc, which the formatter automatically reads
before processing any '-m' options.  More precisely, "troffrc" loads
"papersize.tmac" if the "paper" string is defined, and "papersize.tmac"
in turn sets registers that the groff mm(7) package will honor to give
you the A4 paper format.

> What does 'mmroff' do and I will fake it up.

It runs groff twice.  The first time with `-rRef=1`, which causes
output like this be produced.

.\" IND convolution     1
.\" IND involution      2
.\" Index: index.ind

It collects the `IND` lines, strips the common prefix, and writes them
in sorted order into the file named in the `Index:` line.

It then runs groff a second time, writing the collected and sorted
contents of file named in the `Index:` line into the output at the
location of the `INDP` macro call.

This approach works badly--as in not at all--if the mm document you want
to index is being read from the standard input.  When mmroff runs groff
the second time, nothing remains on standard input to be read and you
get an empty document.

That is a serious limitation, in my opinion.  It also makes mmroff
harder to test.

Another problem with mmroff is that it does not honor GROFF_BIN_PATH as
groff programs are supposed to do.  I have a fix for that in the working
copy of my private post-1.23.0 branch.

So that's 3 problems:

1.  mmroff is inflexible with respect to macro package argument order;
    this order is significant.
2.  mmroff, despite "wrapping" groff, does not behave as groff does with
    respect to reading a document on the standard input.
3.  mmroff does not honor $GROFF_BIN_PATH.

All of these could be solved (the last pretty straightforwardly, and I'm
doing it), but I am beginning to wonder if we shouldn't just drop
mmroff(1) and replace it with a section of the man page that tells
people how groff mm's indexing and reference systems work, and offers
them snippets of sed(1) that they can put into Makefiles.

Simple mm documents--ones that don't use in indexing, referencing, or
`PIC` features, don't need mmroff(1) at all, and the ones that do might
need more power/flexibility than it permits.  For example, they might
want to support multiple index types (for example, "keyword index",
and "subject index").

Thoughts?

Regards,
Branden

signature.asc
Description: PGP signature