Re: Format of html index vs pdf

[Gavin Smith]

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).

> 
> 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 am not sure that an index would be an improvement on the page you
have there.

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
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.)