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
Comments
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? |
Comment author: @dbuenzli I will look into that. |
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). |
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). |
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 |
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 |
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'. |
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. |
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.} |
Comment author: @dbuenzli What prevents you from generating a subsection ? |
Comment author: @Octachron I was unclear: currently in the latex backend, the module title is generated as 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 ). |
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. |
Comment author: @Octachron Fixed in the upcoming 4.06 version, by merging the PR two posts above. |
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
The text was updated successfully, but these errors were encountered: