Improve markup for @-tags

[dbuenzli]

The markup for @-tags is poor. No class labelling for the list of tags, no spans to distinguish the different tag constituents, no class to target/distinguish the different tags

Contrast the markup here:

https://docs.mirage.io/fmt/Fmt/index.html#val-set_utf_8 https://b0-system.github.io/odig/doc/fmt/Fmt/index.html#val-set_utf_8

or here with a few different tags like @since, @deprecated (note the @raise is not used there though)

https://docs.mirage.io/ocaml/String/index.html https://b0-system.github.io/odig/doc/ocaml/Stdlib/String/index.html

Also In general I'd move away from dl for lists of elements: they are harder to style than it should be, because list elements are made of two consecutive blocks of elements rather than a single element. It's much easier to style li elements with properly spanned and classified elements.

[dbuenzli]

No progress here either. This kind of @-tag in CCArray namely:

@since 1.2, but only
@since 2.1 with labels

ends up in the following markup:

<dl>
  <dt>since</dt>
  <dd>1.2, but only</dd>
</dl>
<dl>
  <dt>since</dt>
  <dd>2.1 with labels</dd>
</dl>

The fact that there are two lists actually make it easier to style. But if we'd put that in a single list it would be annoying to style.

But in any case this markup does not allow to use in page search in chrome to find e.g. "since 2.1" which is annoying (In general it seems that in page search in chrome only works across display: inline elements).

A tentative better markup would be to turn that into:

<ul class="odoc-tags">
  <li class="since"><span class="tag">since</span> , 1.2 but only</li> 
  <li class="since"><span class="tag">since</span> 2.1 with labels</li> 
</ul>

[Drup]

It's a bit sad, since that is actually a good use case for dl, but I don't have any opposition to changing the markup to that.

[dbuenzli]

It's a bit sad, since that is actually a good use case for dl

Indeed but somehow dl's model has always been weird from a structural point of view: sequences of pairs of elements. The lack of a surrounding box for each definition makes it harder to style than it can be (though a bit less a problem nowadays that CSS went level 42++)

But the lack of in-page search is deal breaker. Somehow it should be formalized in the standards, AFAIK it's not. I'm also quite annoyed by chrome's search behaviour for inline-block which give us excellent control for the wrapping behaviour for sigs but breaks search.

[dbuenzli]

In #607 we establish the markup structure. The following remains to be done:

1. Coallesce sequences of at-tags in the same list.
2. It seems that @tags can introduce sequences of paragraphs. I'm not sure what's the model here but I find that a bit dubious. Isn't the payload of @tags supposed to be "oneliners" ?

[EmileTrotignon]

This has been raised again on https://discuss.ocaml.org/t/documentation-created-by-dune-build-doc-looks-ugly