ocaml
Cross-references and links are not allowed in headers
ocamldoc was fine with them. Currently this also drops the reference text which is annoying.
I don't exactly see what's the problem with having xrefs in headings.
Example:
https://b0-system.github.io/odig/doc/fpath/Fpath/index.html#ex_append https://erratique.ch/software/fpath/doc/Fpath.html#ex_append https://github.com/dbuenzli/fpath/blob/f679f231ee994e30ca2f5f2b327b3750e9bdf82d/src/fpath.mli#L612
opam install fpath odig
odig odoc -v fpath
[...]
File "src/fpath.mli", line 599, characters 18-28:
'{!...}' (cross-reference) is not allowed in '{2 ...}' (section heading).
Also it seems links ({{:link}link}) are no longer allowed which are then bizzarely turned into em and in the toc aswell (?!).
This is a significant usability issue for tsdl's documentation since we were linking in the documentation of the corresponding C library.
Basically I get lines and lines of:
File "tsdl.mli", line 108, character 12 to line 109, character 41:
'{{:...} ...}' (external link) is not allowed in '{2 ...}' (section heading).
on these kind of heading. A rendering can be consulted here.
I think it would be nice if we could get rid of all these new useless restrictions.
How should a link to a section be rendered, when there is a link inside the link?
If we have:
{1:sec-id {{:https://foo.bar}Foo bar lol}}
blabla blabla see {!sec-id}
then I would suggest render emitting {!sec-id} as <a href="#sec-id>Foo bar lol</a>.
Similarly, the section should become: <h1><a href="https://foo.bar">Foo bar lol</a></h1>
So, to confirm, we allow and retain the nested link for the section itself, but unwrap it for the toc and references?
Three years laters this still significantly degrades the documentation user experience of tsdl's documentation which provides:
> git grep "{[^{]:.* {{" | wc -l
23
direct links to SDL's subsystems documentation and which currently go unrendered.
