Re: Groff's -mm Indexing

[G. Branden Robinson]

Hi Damian,

At 2023-06-30T17:47:43+1000, Damian McGuckin wrote:
> Can somebody tell me how this works please?

The groff_mm(7) page _as it is set to ship in groff 1.23.0_ might be
more helpful than its 1.22.4 incarnation.  I did some work in this area
recently, even after 1.23.0.rc4.

Long story short, because an index needs two passes, you need to
generate the document with mmroff(1), or do your own 2-pass processing.

You got the order right: INITI, IND ..., INDP.  Here's the man page.

Macros
[...]
    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.

    INDP
        Output the index set up by INITI and populated by IND calls.  By
        default, INDP calls SK and writes a centered caption
        interpolating the string Index.  It then disables filling and
        calls 2C; afterward, it restores filling and calls 1C.

        Define macros to customize this behavior.  INDP calls TXIND
        before the caption, TYIND instead of writing the caption, and
        TZIND after formatting the index.

    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.
[...]
Registers
    Default register values, where meaningful, are shown in parentheses.
    Many are also marked as Boolean-valued, meaning that they are
    considered "true" (on, enabled) when they have a positive value, and
    "false" (off, disabled) otherwise.
[...]
    Ref is used internally to control mmroff(1)'s two-pass approach to
        index and reference management; see INITI and RS (Boolean-
        valued; 0).

Does this help?

Regards,
Branden

signature.asc
Description: PGP signature