PR#7363: documentation, start heading levels at 1

[Octachron]

On a suggestion of @dbuenzli, this pull request proposes to start the heading level of all documentation comments at level {1 rather than {6 in the standard library or {2 as the originally intended starting level of normal headings for ocamldoc documentation comments, .

The second commit in this PR corresponds to the straightforward change of heading levels in the documentation.

The first commit is more subtle and alters the semantic of heading levels in ocamldoc to make the heading level {1 available for standard use. Originally, the heading level {1 was implicitly used by ocamldoc for the global module title. Consequently, subheaders needed to start at level {2, forgoing the level {1 in most documentations (since it is quite infrequent to have multiple main titles in the same module).

This first commit acknowledges the natural desire to start counting at{1 and therefore moves up the main module title to an implicit level {0 . It becomes therefore possible to use level {1 for ordinary subheading, whereas the rare cases of multiple main title would have to settle for a more disquieting level {0.

All ocamldoc backend have been update accordingly. In particular, after this patch, the html backend associates a header level <h(n+1)> to the ocamldoc level {n.

To preserve backward compatibility, the default ocamldoc settings preserves the
appearance (for the html backend) or the structure (for the latex and texinfo backends) of the generated files. In particular levels {1 and {0 are rendered in the same way in all backends. Consequently, no documentation using this default setting should be impacted by the hierarchy level change. Similarly, for the reference manual, the combined changes in the first and second commits cancel each other and the generated documentation files are unchanged.

Contrarily, documentations using custom styles would probably have to update their styles.

Finally, the texinfo backend lacked the possibility to customize the mapping between ocamldoc heading levels and the texinfo headings levels. The third commit in this PR adds thus a texinfotitle option that mirrors the latextitle latex option. In particular, it becomes possible to decouple the rendering of level {0 and {1 (which are coupled in the default mapping for compatibility reason).
With this last change, level {1 headings can be used coherently across all ocamdldoc backends.

[dbuenzli]

Why aren't you using 1 here ? The idea is that ocamldoc headers section ocaml modules, so you should restart at 1 here, regardless of whether this is a submodule or not.

[dbuenzli]

(Ok I guess this 3->2 is an automated translation)

[Octachron]

The translation was indeed automated, and you are right I missed the fact that these headers were submodule headers and should retstart at 1. Fixed, thanks.

[Octachron]

I forgot to mention in the description above that this PR also updates the compiler and related tools documentation to start headers at {1, for the sake of consistency.

[Octachron]

Thinking about this PR, it might also be a good occasion to add a new (secondary) default style
that would exploit the newly available {1 heading.

@dbuenzli , any opinion on this subject?

[dbuenzli]

@dbuenzli , any opinion on this subject?

Not really I have been living on alternate stylesheets for ages now. But I think it would be better
to tweak the current one so that both the old scheme and the new scheme look the same (other projects e.g. batteries IIRC still start at 6).

For example that's what I'm doing in odig, I restart 6 as if it is 1, see this comment.

[Octachron]

I have rebased the PR, since it is considered for 4.06.0 integration. One argument in favor for such integration is that it would bundle ocamldoc changes that can break custom ocamldoc style in one version.

[gasche]

Note: my understanding of the 4.06.0 milestone is not "we think this should go into 4.06.0" but "we need to make a decision on this PR (possibly to delay) before 4.06 is released".

[gasche]

I would agree with merging this in 4.06; ocamldoc is lower-risk than other parts of the distribution, and the fact that both you and @dbuenzli like the change means it's probably a good idea.

Could you update the Changes item with a link to this GPR? It is important as it links users to the details of your implementation and its backward-compatibility properties.

There were more ocamldoc-releated potentially-breaking changes than usually in this release cycle. Would you mind writing a small document that lists them, gives a short rationale, and explains the backward-compatibility story? I just looked at the change entries, for some of them it's relatively clear, for the others it's not (for example the Changes entry of the current PR does not explain much about backward-compatibility). I'm thinking of creating another "Detailed changes" for 4.06, I could populate these entries with your content, or link to a specialized document with all advice in one place.

[Octachron]

I have updated the Changes entry to mention both this PR number and that custom css style will probably be broken.

In any case, I agree that writing a small synthetic document for the ocamldoc changes in 4.06 and circulating it is good idea. I will take care of that.

[gasche]

I or someone else can merge (and cherry-pick to 4.06) if the CI is green.

(No need to squash, the commits are cleanly separated.)

[Octachron]

Merged. For the cherry-pick on 4.06, if I am not mistaken, the process is to squash the commit ranges in a single commit?

[gasche]

If you like to keep commit separates, you can cherry-pick each of them. Usually people just cherry-pick the github merge commit, which has the effect of implicit squashing.

[Octachron]

Cherry-picked the whole commit range to 4.06: 8ca16f7^..b61e6e8