On Fri, Aug 12, 2022 at 08:01:06AM -0700, Raymond Toy wrote:
> I created a new index ct and have entries like
>
> @ctindex Package @subentry diag @subentry mat_function
> @ctindex Package @subentry distrib @subentry pdf_normal
>
> The index in the pdf file looks something like
>
> Package,
> diag,
> mat_function <page>
> distrib,
> pdf_normal <page>
>
> This looks really, really nice.
>
> But the html version looks like
>
> P
> Package, diag, mat_function: Functions and Variables for diag
> Package, distrib, pdf_normal: Normal Random Variable
>
> This is perfectly usable, but it would be nice if it could be arranged a
> bit more like the pdf manual to make the distinction between the subentries
> better. I was kind of expecting something more like the pdf version which
> is nice because it shows the hierarchy of the subentries very nicely.
Somebody would have to implement this in HTML. I think it was felt
at the time when implementing the multi-level indices that HTML and
Info indices were not looked at as much as in DVI or PDF. I've no
objection in principle to this but it may complicate automatic processing
of indices in HTML (as in the _javascript_ reader).
The PDF version looks great. :-)
>
> I'm basically trying to replace Documentation Categories
> <https://maxima.common-lisp.dev/docs/maxima_407.html> that is generated by
> using a bunch of scripts to extract categories in the texi sources. Using
> a new index pretty much works just fine at the expense of a one-time cost
> of manually adding all the index entries. It would be nice if the html
> index looked more like the pdf index. Or at least separated out the
> 2-level subentries a little better.
Before creating a new index for every package check that TeX can handle
that many indices. I remember in the past having an issue with the
number of indices because there is a limit of 16 open files for output
in TeX and nothing was done in texinfo.tex to work around this limitation.
I'm not creating a new index for each package. It's just one giant index. There are other entries like "Special Functions", "Elliptic Functions", etc. "Package" is just another entry with 2 subentries: the package name and the function in the package. However, I think this can be modified by adding yet another index to handle Package, so index entries are only 2 levels. That should work out fine.
I am not sure that an index would be an improvement on the page you
have there.
In terms of what's displayed, no, there's not. But that index is created by a bunch of scripts that grovel over the texi files to create a file that is then used to create the actual section.
Using texinfo's indexing feature allows us to get rid of the messy scripts. (I haven't actually converted everything, but the snippet I gave seems to work fine.)
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.
Texinfo side would be needed to produce a page like that Document
Categories one, somehow. I think this is work for the future. (At
the same time, we could also automatically provide some way of cross-
referencing a def block without a need for an extra @anchor to appear
in the source. This is too much change for the immediate future.)
Yeah, I always assumed that you wanted people to insert anchors only as needed.