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?
