Markup for definitions

[dbuenzli]

Note the following is about definitions not code fences.

The markup for definitions could be more semantic and the layout should be improved as it can be pretty bad on long definitions since it may wrap anywhere, something a sensitive OCaml programmer would never do.

First these things would be good to have:

1. The whole definition should be wrapped by a <code> tag.
2. The identifier being defined should be classified via a <span>.
3. The constructors of variants should be classified via a <span> the same way they are classified in textual code spans.

Regarding the layout there are at least two solutions that can be tried.

a) <pre> can be used instead of <div class="def"> and all the formatting is done manually (this is the way ocamldoc proceeds), the disadvantage is that it will not be responsive to the page width.

b) <div class = "def"> is kept but we try to control the line breaking algorithm by only using spaces at the places where we would like to break (e.g. before |, after ->) and using non breaking spaces U+00A0 where we don't want to break. I should then be able to make an indent via css' text-indent.

I have a slight preference to try what b) can give us.

[dbuenzli]

The constructors of variants should be classified via a the same way they are classified in textual code spans.

In fact they are not at all in odoc I was looking at an ocamldoc generated page.

[dbuenzli]

Also word-joiners (U+2060) should be introduced between the ? and the identifier of optional labels.

[trefis]

Do you have examples of classification?

[dbuenzli]

val get : key -> 'a t -> 'a

<span class="keyword">val</span> <span class="value-id">span</span> : <span "type-id">key</span>&nbsp;-> <span "type-var">'a</span>&nbsp;<span "type-id">t</span>&nbsp;-> <span class="type-var">'a</span>

[trefis]

I did some work on that, it's most likely not perfect yet but I think you can already have a look.

[dbuenzli]

It seems identifier (value and type) are not tagged, also you should avoid putting spaces inside the spans (e.g. in val keyword or in ->). Linked identifiers should also be spanned and finally it would be nice not to tag -> as keyword but type-op.

For example:

<span class="keyword">val </span>list : 
<span class="type-var">'a</span> <a href="index.html#/testable.typ">testable</a>
<span class="keyword"> -&gt; </span>
<span class="type-var">'a</span> list <a href="index.html#/testable.typ">testable</a>

should rather be:

<span class="keyword">val</span> <span class="value-id">list</span> : 
<span class="type-var">'a</span> <span class="type-id"><a href="index.html#/testable.typ">testable</a></span> 
<span class="type-op">-&gt;</span>
<span class="type-var">'a</span> <span class="type-id">list</span> <span class="type-id><a href="index.html#/testable.typ">testable</a></span>

[dbuenzli]

@trefis ocaml-doc/doc-ock-html@18ac839 doesn't work: it breaks cut and paste in certain cases (in this case c&p from chrome to emacs on osx).

Basically we should not try to solve this at the character level.

It seems that the forward is to properly span each unbreakable block as suggested above. We should then be able to solve this at the css level (e.g. here are a few suggestions).

[trefis]

Sadness... Thanks for the report.

[dbuenzli]

@trefis notes sometimes definitions remain quite unreadable since the break points remain unpredictable. Along with improving the span classification (e.g. -> still lack a proper class or keyword class) it would be good to <span> parentheses aswell, in conjunction with span { display: inline-block } this makes definitions break at more natural points. Here's an example with a span added for the first argument:

https://jsfiddle.net/0ue5o2t1/

[dbuenzli]

This also works quite well to treat polymorphic types like 'a list as unbreakable tokens by simply surrounding them by a span. I added List.fold_right2 as an example: https://jsfiddle.net/oj63r92m/

[jonludlam]

I wonder if there's any way we can use the work going in on ocamlformat to help here? @Julow
might be able to confirm/deny?

[trefis]

To me, it seems both not obvious and overkill.

[dbuenzli]

I wonder if there's any way we can use the work going in on ocamlformat to help here?

Unlikely, ocamlformat works with a fixed width, on the web your width is not fixed. What I propose in the jsfiddle should work quite well with browser layout engines.

[jonludlam]

Ok, thanks.

[Drup]

As far as I can tell, all of this has been done and/or is regularly improved. The document representation also has support to improve this further. I propose to close this one and move to more focused issues.

[aantron]

I believe none of the points in the original comment have been done. We do have span around ->, though. If you'd like to consider the details of definitions, I suggest opening the more focused issues, and we'll close this one afterwards.

[dbuenzli]

Since #615 the arrows -> are properly classified and were made non breakable, I can hear the screams of joys.

Other than that I concur with @Drup's last comment. The markup for definitions still needs more work w.r.t. break points but in its current state and with respect to all the changes that have occured since it was opened I no longer find this issue to be useful to work with.