Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

stdlib mli files documentation comments, start headers at level 1 #7363

Closed
vicuna opened this issue Sep 19, 2016 · 13 comments
Closed

stdlib mli files documentation comments, start headers at level 1 #7363

vicuna opened this issue Sep 19, 2016 · 13 comments

Comments

@vicuna
Copy link

vicuna commented Sep 19, 2016

Original bug ID: 7363
Reporter: @dbuenzli
Assigned to: @Octachron
Status: resolved (set by @Octachron on 2017-10-05T20:57:35Z)
Resolution: fixed
Priority: normal
Severity: feature
Version: 4.03.0
Target version: 4.05.0 +dev/beta1/beta2/beta3/rc1
Category: documentation
Monitored by: @dbuenzli

Bug description

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.

https://github.com/ocaml/ocaml/blob/trunk/stdlib/scanf.mli#L20
http://docs.mirage.io/ocaml/Scanf.html#7_Functionalinputwithformatstrings

@vicuna
Copy link
Author

vicuna commented Sep 28, 2016

Comment author: @damiendoligez

It's easy enough to change this in the standard library (and I agree starting at 6 is ridiculous) but what will we need to change in the manual/ subtree to maintain the same rendering on all media?

@vicuna
Copy link
Author

vicuna commented Sep 28, 2016

Comment author: @dbuenzli

I will look into that.

@vicuna
Copy link
Author

vicuna commented Sep 28, 2016

Comment author: @Octachron

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).

@vicuna
Copy link
Author

vicuna commented Sep 28, 2016

Comment author: @dbuenzli

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).

@vicuna
Copy link
Author

vicuna commented Sep 28, 2016

Comment author: @Octachron

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

In odoc distinction between the

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".

@vicuna
Copy link
Author

vicuna commented Sep 29, 2016

Comment author: @dbuenzli

In fact the solution of using h2 for "{1" seems to be a better real world compromise. Noone seems to be supporting the html outline algorithm:

https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Using_HTML_sections_and_outlines

@vicuna
Copy link
Author

vicuna commented Oct 1, 2016

Comment author: @Octachron

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'.

@vicuna
Copy link
Author

vicuna commented Oct 1, 2016

Comment author: @dbuenzli

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.

@vicuna
Copy link
Author

vicuna commented Oct 1, 2016

Comment author: @Octachron

The semantic of '{1' needs to be consistent across all backends supported by ocamldoc, in particular to keep an uniform output for the ocaml manual.

Currently, '{1' is at the same level that the global module title, so using '{1' in array.mli, for instance, will lead to

\section{Module {\tt{Array}} : Array operations.}

\section{Iterators}

with no way to distinguish between the module level and the iterators subsection.

@vicuna
Copy link
Author

vicuna commented Oct 2, 2016

Comment author: @dbuenzli

What prevents you from generating a subsection ?

@vicuna
Copy link
Author

vicuna commented Oct 2, 2016

Comment author: @Octachron

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 #830 first commit for the required change in the latex backed( and the third commit for the texinfo modifications ).

@vicuna
Copy link
Author

vicuna commented Oct 5, 2016

Comment author: @damiendoligez

I'm setting the target version to 4.05. Speak up if you have a very good reason to include the change in 4.04.

@vicuna
Copy link
Author

vicuna commented Oct 5, 2017

Comment author: @Octachron

Fixed in the upcoming 4.06 version, by merging the PR two posts above.

@vicuna vicuna closed this as completed Oct 5, 2017
@vicuna vicuna added this to the 4.05.0 milestone Mar 14, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants