Re: Format of html index vs pdf

[Raymond Toy]

On Fri, Aug 12, 2022 at 9:46 AM Gavin Smith 
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  
> >   distrib,
> > pdf_normal 
> >
> > 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
> >  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

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  
>   distrib,
> pdf_normal 
> 
> 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
>  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.)

Format of html index vs pdf

[Raymond Toy]

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  
  distrib,
pdf_normal 

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.

I'm basically trying to replace Documentation Categories
 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.








































-- 
Ray