HTML markup, move away from tables

[dbuenzli]

Tables are being used for documenting type cases and record fields.

This doesn't work in practice for the same reasons mentioned here for module synopses; basically don't use table/alignement if you don't know how long things are going to be beforehand.

Here's an example with two stylesheets that show the problem and how ugly it is no matter the page width:

https://b0-system.github.io/odig/doc/biniou/Bi_inbuf/index.html
https://b0-system.github.io/odig/[email protected]/biniou/Bi_inbuf/index.html

I propose to move to ordered lists ol, with one li per definition and a twist (if the logic is easy to implement):

• If the doc string of the definition is only made of inline content we span it after the code.
• If the doc string of the definition is made of multiple paragraphs we div it.

Basically we move from:

table
  tbody
    tr
      td.def
        code
      td.doc

to

ol
  li.def 
    code
    (span | div).def-doc

With appropriate styling this allows HTML renderers to

1. Have the code and a one-liner doc string on a single line and break and indent whenever either of these no longer fits the page width.
2. Have the code on its own break and indent line and a multi-paragraph doc string separately rendered below like top level specifications do.

The scheme should be able to accomodate short and long styles of documenation:

{ incr : int; (** The position increment. *)
  f : ...;
  (** This field has the function for bla bla. It takes the following arguments. 
      {ul ... } *)
  decr : int; (** The position decrement *) }

Rendering the thing as:

{ 
   incr : int;    The position increment.
   f : ...;
      This field has the function for bla bla. It takes the following arguments:
       - ...
   decr : int;    The position decrement.
}

Besides by using: user-select:none on .def-docit should be possible to reasonably c&p the definitions; but unfortunately not the content of the doc strings themselves becomes no longer selectable, but from an ergonomic point of view I think you are interested in selecting the definitions most of the time (e.g. because you want to c&p to pattern match on all the cases of a value).

Note that applying this to the example mentioned above this will result in 1. which will be ugly. But we argue that the authors should introduce paragraphs. In fact the source already has them albeit not with the blank line that this supposed to separate them.

/cc @Drup

[Drup]

The latex backend uses the exact same heuristic: inline when it's less than a paragraph, block otherwise. We can reuse the logic (and probably move it to document/, it seems like it's a general concept and it'll help with consistency).

We can probably use a touch of flexbox to make the display more reactive too (regardless if we use ol or something else).

[Drup]

@dbuenzli the HTML part is implemented here : https://github.com/Drup/odoc/tree/heuristic-docsrc
Can you do the CSS adjustment ? You'll do it better/faster than I would.

[dbuenzli]

Can you do the CSS adjustment ?

I wonder in what kind of trap you are trying to get me into :-) but yes I can do that. How do you want to proceed ?

[Drup]

I wonder in what kind of trap you are trying to get me into :-) but yes I can do that. How do you want to proceed ?

:innocent look: Just trying to be efficient!

Just take the commits and make a PR with them. I fixed a bug about the various class attributes overriding each other on the way.

[dbuenzli]

Ok ! (Not sure I'll do it today though)

[Drup]

That didn't work so well. :p

I'll make a PR and then other people can chime in for the CSS.

[dbuenzli]

Oups sorry I completely forgot about that. A bit on other deadliny things right now. But yes starting by doing the PR could motivate me to find a bit of time.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. The main purpose of this is to keep the issue tracker focused to what is actively being worked on, so that the amount and variety of open yet inactive issues does not overwhelm contributors.

An issue closed as stale is not rejected — further discussion is welcome in its closed state, and it can be resurrected at any time. odoc maintainers regularly check issues that were closed as stale in the past, to see if the time is right to reopen and work on them again. PRs addressing issues closed as stale are as welcome as PRs for open issues. They will be given the same review attention, and any other help.

[Julow]

Do we still use any table in the html generator ? I'd like to confirm the status of this issue as it was closed by the bot.

[panglesd]

No, since #830, if my grep does not lie. (Apart from explicit tables in the upcoming #893 but that does not count).

[Julow]

Thanks!