HTML structure broken on master

[dbuenzli]

It seems the merge of PR #627 broke the HTML structure. See the comment here.

[dbuenzli]

Just to make things clear the HTML structure of a module is as follows:

body.odoc 
  nav.odoc-nav          (* global nav *) 
  header.odoc-preamble  (* module or .mld preamble *)
  nav.odoc-toc          (* page nav *)
  div.odoc-content      (* module or .mld contents *)

The docs of a module should be allocated to these elements as follows:

• Docs before the first structure item or heading (of any level) should go in header.odoc-preamble, all remaining docs should go in div.odoc-content.
• Besides, since that does not seem to be well understood. The first paragraph of header.odoc-preamble (if any) is also what defines the module synopsis.

[Julow]

If I understand correctly, this issue is related to #235 and both can be solved in the same way.
Since #627, the top-comment of a signature is composed of the comment attached to its definition and the top-comment from its expansion, see #478 (comment).
That didn't break the HTML structure but that exacerbated the first issue. Before, most comments were not in the preamble, only the comment attached to the definition was.

These issues can be fixed by splitting the "composite top-comment" at the first heading, the first part goes into the preamble and the rest, starting from the first heading, in the content and is available in the TOC.
You also proposed a fix for this here #235 (comment), which goes further and consider every comments before the first item to be part of the "composite top-comment".

Besides, since that does not seem to be well understood

Odoc didn't have any code for handling synopsis 16 days ago, #597.
That's not how ocamldoc does it, it takes the first sentence of whatever is the first element. (paragraph, heading and even verbatim blocks)

[dbuenzli]

These issues can be fixed by splitting the "composite top-comment" at the first heading, the first part goes into the preamble and the rest, starting from the first heading, in the content and is available in the TOC.

Yes, but it's stop at first heading or structure item (ocaml specification).

You also proposed a fix for this here #235 (comment), which goes further and consider every comments before the first item to be part of the "composite top-comment".

Yes that's the same as what I suggested above. As mentioned there talking in terms of comments as unit doesn't really make sense, you want to talk in terms of blocks of the ocamldoc language.

That's not how ocamldoc does it, it takes the first sentence of whatever is the first element. (paragraph, heading and even verbatim blocks)

My bad, apparently it does, but as seen in #628 in a confusing way. We suggested to change that a long time ago and nowadays it seems everyone agrees, see the discussion and further references in #597.

[dbuenzli]

Odoc didn't have any code for handling synopsis 16 days ago, #597.

Btw. that's not entirely true. It didn't have synopses for the !module directive but odoc had synopses for module definitions from a very long time. See e.g. here for rendering example with an older odoc.

Just to make sure: does that mean that we have two different code paths for that ?

[Julow]

Odoc don't do synopsis (#632).
Uucp has comments attached to its definitions: https://github.com/dbuenzli/uucp/blob/master/src/uucp.mli#L36

[dbuenzli]

This has been fixed by #640.