A bit of an uninteresting work and issue but it seems that in the stdlib headers in comments start at level 6 which means that subheaders are 7 which is a div with class .h7 since h6 is the last html header tag you can get. TBH I find that a bit ridiculous.

Many (most ?) libraries out there simply start at {1 } which is the natural thing to do when you write your comments in an mli file.

In my stylesheets I restart the style at h6 so that they look like h1 but I think that the stdlib should be changed to start at 1 so that sub-heading (now fake 7, after h2) can benefit of semantic markup.

Here's an example of a level 7 header and it corresponding div in ocamldoc generated documentation.

I believe that starting the standard library subheaders at "{2" rather than "{1" would make more sense for both html and TexInfo rendering.

In ocamldoc html rendering, the 'h1' level is used for the module name/main titles, and subsequent headers are not nested. I think it makes sense to distinguish at tags level between the module title level and the subheader title and thus use "{2" rather than "{1". As a side bonus, the current stylesheet uses the same style for 'h2' (respectively 'h3') and 'h6' (respectively 'h7') and would not need to be updated.

On the latex side, the manual already remaps '{6' to level 2(subsections) and '{7' to level 3 (subsubsections). Updating the latex rendering of manual is therefore just a matter of adjusting the makefile 'manual/manual/library/Makefile'.

The more delicate situation might be the TexInfo manual that uses the raw ocamldoc level, and already uses the level '{1' for the module level. Using '{1' in the standard library documentation would mess up the structure of this manual. Contrarily, starting at '{2' preserves this structure and the existing tables of content (and create some new tables of content).

There's a lot of code out there that use "{1" for main separations since it's the natural thing to start from when you are writing documentation in your modules: there nothing that actually tells you that there is an implied "{1". Given this I don't think it makes any sense for programmers to write "{2" (or teach them to do so): it would mean that you would never use "{1".

In odoc distinction between the <h1 of the module and subsequent ones introduced by "{1" will occur by wrapping the whole module preamble in a <header tag and the rest in a <section tag which will provide correct result for the HTML5 outline algorithm despite headers being at the same level.

Other schemes like generating <h2's for "{1" are of course possible since nothing says in the ocamldoc language that "{1" means h1. It just says it's the highest level of grouping in a module.

In any case in odig's stylesheets what is generated by "{1" (and currently "{6") is the level that will give you the largest headers with a slight sectioning ruler which won't be provided by "{2". Also I think that currently odoc will map "{7" to h6, I personally won't report this as a bug since I see the usage of "{7" as being a bug).

I agree that starting with '{2' and forgoing '{1' is not really natural (even if ocamldoc documentation does follow this pattern).

<blockquote>
In odoc distinction between the <h1 of the module and subsequent ones introduced by "{1" will occur by wrapping the whole module preamble in a <header tag and the rest in a <section tag which will provide correct result for the HTML5 outline algorithm despite headers being at the same level.
</blockquote>

This sounds like the cleanest solution, I think that it might be worthwhile to backport it to ocamldoc.

Going in this direction, the texinfo manual problem with '{1' could be fixed by
adding a "texinfotitle" option to ocamldoc texinfo generator, matching the latex option "latextitle".

Generating h(n+1) for "{n" is more or less equivalent to moving the global module title to an implicit "{0" level.

In particular, to make this change works with the latex version of the manual, the latex generator would need to generate a level "{0" title for the global module title.

At some level, it is quite elegant to use the level 0 for a heading level that should be never used without very good reasons. However, this is quite an involved change compared to simply starting at '{2'.

I don't get this, I'm simply talking about generating h1 for the module name and h2 for {1 in the *html* backend.

For the reasons mention above I think it's better if we can make everyone standardize on {1 as the first level you use in your modules, any other number doesn't make any sense, unless you never want to use those that are above.

I was unclear: currently in the latex backend, the module title is generated as
a level 1 title, i.e {1 Module name }. It was therefore not possible to remap independently the module title to '\section' and other '{1' titles to '\subsection*'.

Not that the change needed is too heavy: see https://github.com/ocaml/ocaml/pull/830 [^] first commit for the required change in the latex backed( and the third commit for the texinfo modifications ).