Tagging system for Texinfo

[Gavin Smith]

On Fri, Aug 12, 2022 at 12:17:17PM -0700, Raymond Toy wrote:
> > It's possible that Texinfo should have more support for this kind of
> > thing (and API documentation in general) although I am not sure what
> > to suggest.  It looks like you are doing a pretty good job as it is
> > with the page.
> >
> > As there is already an index entry being created by the @def*
> > command produces the definition block, as at
> >
> > https://maxima.common-lisp.dev/docs/maxima_211.html#index-mat_005ffunction
> >
> > ideally, the extra @ctindex wouldn't need to be in there and the
> > package name could be included in the @def* command.  Something on the
> >
> 
> Unfortunately this doesn't quite work.  Functions can be in more than one
> category.  For example, bessel_j is in both the Special Functions category
> and the Bessel Functions category.

Yes, I remember this was discussed before.

https://lists.gnu.org/archive/html/help-texinfo/2021-12/msg00012.html

I've added it to the TODO file but don't know if/when/how it can be
implemented.

I'm imagining some syntax like

    @def bessel_j (@var{v}, @var{z}) @tag{Function} @tag{Bessel Functions}@
                                     @tag{Special Functions}
    The Bessel function of the first kind...
    @end def

This could be output as something looking like

    bessel_j (v, z)          [Function] [Bessel Functions] [Special Functions]

        The Bessel function of the first kind...

The "category" of definitions becomes a tag, so "@deffn {Func} foo" becomes
equivalent to "@def foo @tag{Func}.

Several questions come to mind (there may not be easy answers to these):

* Would the tagging system be an extension of the index system or
ancillary to it?
* Do we format pages listing tags like index pages?
* Do we have tag pages just for HTML output, or do we do something for
TeX/PDF/other formats as well?
* How easily could we implement "keyword" arguments like @tag{}?  We already
have @sortas{} for index entries - could we implement keyword arguments as
part of a unified scheme?  (I remember whitespace handling around @sortas
was awkward.)
* Is this even worth implementing, would Maxima use it, and what other
projects would be likely to use it?
* Is tagging just for @def-like commands or can other things get tagged
as well?