Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0007363OCamldocumentationpublic2016-09-20 00:382017-10-05 22:57
Reporterdbuenzli 
Assigned Tooctachron 
PrioritynormalSeverityfeatureReproducibilityalways
StatusresolvedResolutionfixed 
PlatformOSOS Version
Product Version4.03.0 
Target Version4.05.0 +dev/beta1/beta2/beta3/rc1Fixed in Version 
Summary0007363: stdlib mli files documentation comments, start headers at level 1
DescriptionA 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 [^]
TagsNo tags attached.
Attached Files

- Relationships

-  Notes
(0016360)
doligez (administrator)
2016-09-28 14:53

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?
(0016361)
dbuenzli (reporter)
2016-09-28 15:02

I will look into that.
(0016365)
octachron (developer)
2016-09-28 19:06
edited on: 2016-09-28 19:07

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

(0016367)
dbuenzli (reporter)
2016-09-28 20:55

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).
(0016370)
octachron (developer)
2016-09-28 22:51
edited on: 2016-09-28 23:12

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

(0016373)
dbuenzli (reporter)
2016-09-29 14:59

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 [^]
(0016379)
octachron (developer)
2016-10-01 23:05

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'.
(0016380)
dbuenzli (reporter)
2016-10-02 00:11

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.
(0016381)
octachron (developer)
2016-10-02 00:27

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.
(0016382)
dbuenzli (reporter)
2016-10-02 02:13

What prevents you from generating a subsection ?
(0016383)
octachron (developer)
2016-10-02 12:17

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 ).
(0016392)
doligez (administrator)
2016-10-05 16:38

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.
(0018492)
octachron (developer)
2017-10-05 22:57

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

- Issue History
Date Modified Username Field Change
2016-09-20 00:38 dbuenzli New Issue
2016-09-28 14:53 doligez Note Added: 0016360
2016-09-28 14:53 doligez Status new => acknowledged
2016-09-28 14:53 doligez Target Version => 4.04.0 +dev / +beta1 / +beta2
2016-09-28 14:53 doligez Target Version 4.04.0 +dev / +beta1 / +beta2 => undecided
2016-09-28 15:02 dbuenzli Note Added: 0016361
2016-09-28 19:06 octachron Note Added: 0016365
2016-09-28 19:07 octachron Note Edited: 0016365 View Revisions
2016-09-28 20:55 dbuenzli Note Added: 0016367
2016-09-28 22:51 octachron Note Added: 0016370
2016-09-28 23:12 octachron Note Edited: 0016370 View Revisions
2016-09-29 14:59 dbuenzli Note Added: 0016373
2016-10-01 23:05 octachron Note Added: 0016379
2016-10-02 00:11 dbuenzli Note Added: 0016380
2016-10-02 00:27 octachron Note Added: 0016381
2016-10-02 02:13 dbuenzli Note Added: 0016382
2016-10-02 12:17 octachron Note Added: 0016383
2016-10-05 16:38 doligez Note Added: 0016392
2016-10-05 16:38 doligez Target Version undecided => 4.05.0 +dev/beta1/beta2/beta3/rc1
2017-02-23 16:35 doligez Category OCaml documentation => Documentation
2017-02-23 16:44 doligez Category Documentation => documentation
2017-03-07 14:04 shinwell Severity minor => feature
2017-10-05 22:57 octachron Note Added: 0018492
2017-10-05 22:57 octachron Status acknowledged => resolved
2017-10-05 22:57 octachron Resolution open => fixed
2017-10-05 22:57 octachron Assigned To => octachron


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker