Description
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
spanit after the code. - If the doc string of the definition is made of multiple paragraphs we
divit.
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
- 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.
- 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