On Fri, Aug 12, 2022 at 9:46 AM Gavin Smith <[email protected]> wrote:
> 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. Thanks for your help. -- Ray
