Multipage manual in odoc

[voodoos]

Since #61, one can write manuals in odoc by creatings .mld files and cross-referencing them.

However the left sidebar that contains the table of content will always show only the opened file structure, without links to other pages of the manual.

This makes the discovery of pages of the manual quite difficult as one has to look for links in the text. I think it would be more useful to display in the sidebar, in addition to the detailed outline of the current file, links to the other pages of the manual.

It is not obvious how the list of page-links should be made. It could be established in a number of ways:

• List only the pages which are referenced from the current page.
• List the pages referenced in the current page and the ones that reference the current page.
• List all the .mld files in the current folder
• A tree-display of the .mld files in the folder and its subfolders

Another issue would be the name to display in the side bar. It could be:

• The name of the file
• The first header {1 ...} in the file

Example

It could look like that in a three-pages manual :

Where "Emacs reference" and "Vim reference" are not headers of the main page but links to two other pages of the manual named Emacs reference.mld and Vim reference.mld.

[trefis]

I'm not fond of the suggestions you make regarding how to populate the sidebar:

• List only the pages which are referenced from the current page.

This seems both fairly adhoc, and potentially annoying: what if I'm linking to some page that I don't want to appear there?

• List the pages referenced in the current page and the ones that reference the current page.

Definitely not fond of such a non-local analysis (and it also seems fairly fragile), though I guess it could be done during the "link" step.

• List all the .mld files in the current folder
• A tree-display of the .mld files in the folder and its subfolders

There is no semantic notion of folders. Apart from that, notice that it's something we could already do with compilation units, but do not.

My personal take on the topic is that, for now, you should structure your "manual" in the same way you structure your API docs: the "landing page" should link you to all the relevant places, and it should always be easy (i.e. there should only be one step) to jump back to that page.
As for the future: perhaps in .mld (though I'm not sure why they'd be different in that respect) you want to manually write your side bar, or rather: you want to manual write additions to the generated sidebar. It doesn't seem crazy to me to add a new construct to the markup-language just for that (and it would also be usable in API pages, which seems nice)

[dbuenzli]

I also have @voodoos needs, but I concur with @trefis.

Note that the language already has things like {!modules: moduleid moduleid... } and {!indexlist} directives, though those are for the page content.

We could add something like a {!toc-xrefs: pageid moduleid... } directive to help populate the toc with specific entries to other pages and/or module pages in a controlled manner.

[jonludlam]

We had a discussion about this sort of issue a few weeks ago during a dev meeting. We came up with a proposal that should help - the draft design doc is on the wiki here: https://github.com/ocaml/odoc/wiki/Document-Tree-model - comments and suggestions would be really helpful!

[dbuenzli]

@jonludlam I'd need more effective details to form a concrete opinion but I'm a bit skeptical about the proposal:

1. This seems to be very hierarchically oriented. I don't think hierarchical organisation is such a good fit for organising documentation. The problem with hierarchies is that it doesn't work well as soon as you want something in two different places. You want lateral moves, you want a web.

2. The system looks too flexible to me. You want to enforce some regularity so that not every package out there starts implementing its own way of presenting documentation.

An example for 1. Suppose I have a tutorial in a .mld document that is specific to a module, I would like to have a direct link in the sidebar of that module. I would also likely have that tutorial in the side bar of e.g. a more general documentation page of the package. I don't think I can achieve that with your proposal – this possible with the very simple proposal I have given above.

[lpw25]

@dbuenzli With respect to 1, I think that the documentation is already very hierarchically oriented due to the APIs themselves being hierarchical. Allowing this hierarchy to be extended to include the pages as well is I think very natural. Whilst you sometimes want to have non-hierarchical structure, you do sometimes just want the hierarchy (e.g. wanting the main page of a library to contain all the modules in the library).

I think that adding the ability to include other items in the table of contents is very reasonable, but when I have a simple hierarchy I would like to get the obvious thing by default without needing to do such customisation. In other words, I think your feature can be considered separately and in addition to the pages proposal.

With respect to 2, the flexibility is deliberate. I'm in favour of there being opinionated views on how packages/libraries layout their documentation, but I do not believe that odoc is the place those opinions should live. I originally tried to have a very unopinionated notion of -package: it has no specific semantics beyond containment and exactly what should map to it was left to the surrounding tools (e.g. an opam package, an ocamlfind library, an oasis package, etc.). However, even this has turned out to be too opinionated as the conventions around OCaml library packaging have evolved. Rather than trying to e.g. add a notion of "library" within "package" or generally try and guess what people will want to do next, I think it is better for odoc to have a simple flexible system and let the build systems and package managers decide how best to use it.

[dbuenzli]

Just to make clear I'm not against the proposal, I have now written quite extensive .mld documents an have seen their limits and I'm glad there is discussion to blow these. But I'd really like to see a proper detailed design doc with operational details and the resulting navigation structure to be able to form an opinion.

@dbuenzli With respect to 1, I think that the documentation is already very hierarchically oriented due to the APIs themselves being hierarchical.

It's not because APIs are hierarchical, that your high-level documentation should be. On the contrary, it should rather not be and provide meaning across the API hierarchy (and as for the hierarchy in those documents someone recently pointed to me again that the feynman lectures on physics covers all of physics from celestial mechanics to quantum electrodynamics with just two hierarchical levels…).

With respect to 2, the flexibility is deliberate. I'm in favour of there being opinionated views on how packages/libraries layout their documentation, but I do not believe that odoc is the place those opinions should live.

I think one should be careful with that, arbitrary organisation is not a good thing for end-users, in the end the language and the the way libraries are installed (and maybe in the future namespaced) do already provide organisation system itself and I think it would be wrong to ignore it.

One of the virtue of ocamldoc docsets is that they are the same whichever library you are using and the metric number of clicks to toplevel entry points is extremely low.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. The main purpose of this is to keep the issue tracker focused to what is actively being worked on, so that the amount and variety of open yet inactive issues does not overwhelm contributors.

An issue closed as stale is not rejected — further discussion is welcome in its closed state, and it can be resurrected at any time. odoc maintainers regularly check issues that were closed as stale in the past, to see if the time is right to reopen and work on them again. PRs addressing issues closed as stale are as welcome as PRs for open issues. They will be given the same review attention, and any other help.