Also, I would like to point out the Troff submodule with some artistic semantics to make things tractable: https://github.com/Drup/odoc/blob/4d68e9827dc121c0aa2538df57cfb93e837c95ff/src/manpage/generator.ml#L25-L55. If anyone wants to delve into the semantics of groff commands and improve that, I would be happy to pass on the flame ...

It seems to me that includes should always be expanded, perhaps with a header above saying where they came from - otherwise it might not even be possible to see the accurate contents (e.g. include Foo with type t := int).

I wouldn't have thought submodules should be expanded inline, otherwise man stdlib would be huge (and man core_kernel larger!) - I agree with the idea of enabling man package.Foo.Bar

Where you say

I'm tempted to output pages only for actual modules (and documentation pages)

do you mean not outputting them for module type/classes/etc?

Functors are a bit more interesting - perhaps we might expand each of the parameters at the top inline in the page?

Also: this is really great! Thanks for all the hard work you're putting into this!

It seems to me that includes should always be expanded, perhaps with a header above saying where they came from - otherwise it might not even be possible to see the accurate contents (e.g. include Foo with type t := int).

That was my initial idea as well, but I have not yet managed to find a layout making the header clear.

I wouldn't have thought submodules should be expanded inline, otherwise man stdlib would be huge (and man core_kernel larger!) - I agree with the idea of enabling man package.Foo.Bar

In more details, my current idea was to expand anything that does not get its own page. man stdlib would still be reasonable, since all the submodules have their own page. The question becomes: for what do we generate a page. The only choice I see which never causes any collisions is to generate a page only for modules with a valid (OCaml) path: Yes for A.B.C, no for A.B.module-type-C and no for A.module-type-C.B. Concretely, Map.S is expanded and Map.Make gets its own page.

An alternative choice would be to generate pages for everything that has a valid OCaml path. This is the choice made by ocamldoc, but then we can get collisions, and I'm not sure what to do with those.

The user already has control over whether an include should start expanded or not in the html. I think you should just use that setting for deciding whether to show the contents of an include or not.

I wasn't clear. I'm mostly talking about regular declarations here, not includes:

module type S = sig
  <put the content here>
end

The problem for includes is more about the actual layout.

Your current idea sounds fine to me @Drup - so we never give a separate page to an identifier that contains a module type.

Should we special-case Stdlib? Or at least give an option to allow it - we can currently do man List but with the suggestions above that would be man ocaml.Stdlib.List.

I think following ocamldoc and then just letting say modules shadow module types if there is a collision is probably fine. This is much less problematic than usual because you have no links, so there is no risk of creating dead links by dropping a page.

I'm done with the first version.

I modified the IR to inline subpages at the semantically relevant place. For instance, for a module type with a subpage, we have some IR equivalent to module type FOO (= ModExpr) where the part in parens have additional content indicating the IR has a summary for a subpage.

The HTML renderer ignores those (for now), but the manpage one will inject the subpage when appropriate.
Here's what it looks like with some headers:

I expect this to be very useful for the LaTeX renderer, as well as opening the way for interesting HTML tweaking.

For the rest, I did as discussed: modules and classes have their own pages, everything else is injected. The files are named Path.To.thing.3o. The high-level layout is rather decent now, although some finer rendering could be improved.

Here are various things that requires further work:

• There is some code duplication between html and manpage output, but I think fixing this should go in a larger patch working towards a more modular system
• I'm again not happy with the output for functors.
• Heading nested insides included pages do not work as well as they should, but I'm not even happy with the HTML output there, so that'll go in a separate patch.

ping @aantron :)

Thank you!