Re: Groff's -mm Indexing

[G. Branden Robinson]

At 2023-07-01T14:55:31+1000, Damian McGuckin wrote:
> Sorted.
> 
> The new system won't really work because it uses \n[%] which is not
> what I want to get as a page number. I want \nP because I reset it to
> zero after the abstract.

Isn't this the "heading mark"-based indexing that groff mm already
supports?  You get at this by calling `INITI` with `H` as its first
argument.

Maybe not, though.  Looking at it, it's a bit clumsy--it really does use
the "heading mark", e.g. "1.", "2.", "2.1.", "3.5.9", etc.  Complete
with the two fixed-width spaces that separate this mark from a run-in
heading.

Further, there already exists a string without those trailing spaces,
`hd@mark-trimmed`, which is what it seems `IND` should be using, but it
doesn't.

Did I mention that there are a lot of loose ends in groff mm?

I'm not sure why section-page numbering, which is supported for page
headers (and is a DWB mm feature) is not supported for index entries.  I
can look into that.

Beyond that, it occurs to me that we could easily support a completely
general index entry format with two changes.

Reviewing the macro interface real quick:

    INITI location-type file-name [macro]
        Initialize groff mm's indexing system.  Argument location-type
        selects how the location of each index entry is reported.  file-
        name populates an internal string used later by INDP.

        location-type   Entry format
        N               page number
        H               heading mark
        B               page number, tab character, heading mark

        If macro is specified, it is called for each index entry with
        the arguments given to IND.

    IND argument ...
        If the Boolean register Ref is true, write an index entry as a
        specially prepared roff comment to the standard error stream,
        with each argument separated from its predecessor by a tab
        character.  The entry's location information is arranged as
        configured by the most recent INITI call.

We could:

1.  Make `INITI` recongize a "location-type" argument of 'C' (for
    "custom"), where the entry format is whatever the user supplies as
    the arguments to `IND`.
2.  Make `IND` require two arguments minimum if the "location-type" is
    'C'.

But before I mess with that I think I want to support 'S' for
section-page numbering in the index, and audit use of `hd*mark` to see
if it's being used other places where `hd@mark-trimmed` should be.

> I looked at the ultimate documentation (the macros themselves).

A wise choice.  You won't be seeing very robust input validation.  I've
added that for post-1.23.0.  I'm attaching my current version.

> I can see my old friend .IX which sends its argument and page number
> to standard error.

Yup, I took that out for groff 1.23.0 too.

NEWS:
o The m (mm) and s (ms) macro packages no longer implement the `IX`
  macro.  This undocumented 4.2BSD ms extension was similarly
  undocumented by groff mm and ms.  No documents applying it are
  attested.  groff mm documents its own indexing feature, `INITI`.  We
  otherwise suggest makeindex(1), which supports troff and is available
  with most TeX distributions, for your mm/ms document indexing needs.

> I can define my own and uses that to output a list of key
> words/phrases and their page numbers which I can capture.

I think leaving `IX` unmolested for users to manage their own indexing
is the right choice here, especially given that `INITI`/`IND`/`INDP` is
not fully baked for the scenarios we really should support.

> I will sort and massage that list into a file and do much of what
> .INDP does and then pull that file into my document with a .so.

Sounds good to me.

> All good.

Thanks for giving groff mm attention.  It has evidently been missing
user feedback for quite a while.

Regards,
Branden

m.tmac
Description: Text document

signature.asc
Description: PGP signature