{!indexlist} not supported and/or alternative unspecified

[jonludlam]

[dbuenzli]

This is also tracked and discussed in #52.

I'm don't know if the directive itself has to be supported (except maybe to link on the index page) but it would be nice to find a scheme to be able to generate an index page for a set of odoc(l)? files. They allow to quickly glance the names that exist which can be useful for design and provide a poor but effective man's search via the browser's in-page search.

For example in odig we could have an index page per package + an index page for all packages. As I mentioned in #52. I don't think it's necessary to have separate indexes for types and values like ocamldoc does.

[jonludlam]

Next step: come up with a suggestion for what we should do!

[dbuenzli]

Next step: come up with a suggestion for what we should do!

Here's a (maybe too) simple suggestion. Add an odoc mld-index [ -o MLD] ODOC... command that simply spits out an .mld file with the index for the given odoc files.

[Julow]

{!indexlist} is generating links to the indexes and not the indexes themselves. This doesn't apply to Odoc and is replaced by --parent/--child and the sidebar.
It's currently the driver's responsibility to generate indexes, Odoc wouldn't have more informations than the driver here.
If we wanted to make generating the indexes easier, my suggestion would be to add a {!children} markup that purpose (similar to what {!modules: ...} should do).

[dbuenzli]

@Julow I'm afraid I can't make sense of what you are saying. In any case there is no provision to generate indexes of values, types and modules in odoc at the moment and I think one should be added.

[Julow]

Indeed there is no way to generate indexes like ocamldoc does. My comment above is about listing compilations units, which doesn't make sense.

The data contained into indexes would be useful for other purposes so I suggest adding a command to extract that information from odoc files: odoc index [-o SEXP] ODOC....
This can be useful to build complex features outside of odoc, like search or to build custom indexes (eg. when building the documentation of several packages).
That is not incompatible with mld-index, which would be useful when building the documentation for a single package.

[avsm]

odoc dev meeting notes:

There is some confusion among the odoc developers (!) what indexlist precisely does. For reference, the ocamldoc manual says:

{!indexlist} | insert a table of links to the various indexes (types, values, modules, ...). Used in HTML only.

We need to figure out the way forward for two distinct features:

• how to generate toplevel modules list (something like {!modules} but without the manual list). @Drup investigating what this is (in Batteries/Lwt?)
• how to generate indexes of available types/values/modules

We don't need to stick to the ocamldoc syntax for this, if something newer works better. This is because the ocamldoc syntax is marked in the manual as for the HTML backend only, so it's a backend-specific bit of syntax that could be adapted to fit odoc better.

[Drup]

• how to generate toplevel modules list (something like {!modules} but without the manual list). @Drup investigating what this is (in Batteries/Lwt?)

I was convinced it existed (and apparently I was not the only one), but neither @Octachron nor I can find it again, so I guess we had a collective hallucination.

how to generate indexes of available types/values/modules

During the dev meeting, we decided to follow @Julow 's plan: 1) discontinue support of the indexlist command itself 2) Eventually (after 2.0) support automatic generation of indexes with an auxiliary command, which will be linked from the sidebar.