Documentation of odoc is bad

[jonludlam]

Some considerable effort needs to be made to improve it.

[avsm]

Progress towards this in #571 to document the supported interfaces.

[kenichi-asai]

Is odoc documentation available somewhere now? I want to know whether odoc supports custom tags found in ocamldoc (or any other way to produce documents in two languages), because it seems customs tags in ocamldoc are no longer developed: ocaml/ocaml#6707

[Columbus240]

A concrete problem: odoc currently links to the syntax reference of ocamldoc, but doesn't accept precisely the same syntax. The differences should be explained somewhere (or be linked in the README if such a document already exists).

I found the following differences between the syntax reference and odoc v1.5.3:

• ocamldoc allows arbitrary heading levels, but odoc only allows levels from 0 to 5.
• odoc doesn't interpret target-specific formatting as ocamldoc did. Namely {%latex: ...%} throws a warning and instead of ignoring the contents of the braces, the contents are printed.

Edit: The second point is fixed in the master branch. odoc now behaves like ocamldoc in this respect.

[jonludlam]

Fixed by #733. Or at least, the situation is better than it was!