Latex backend

[Octachron]

This PRs adds an initial latex backend that can compile the OCaml standard library quite nicely.

During the implementation, @Drup and me modified the documentation IR to allow backends to take more easily the decision to inline submodules and other subpages, since for a latex backend we try to generate readable paper texts, where following link is not so immediate.

The backend probably some need more testing with other libraries and more tuning with people feedback.
A remaining point is the question of the user interface, currently, I am using a hand-written makefile combined with a handwritten latex header file. I was wondering if we should provide a template latex header but this is not done yet.

[jonludlam]

There are some post 4.02 function calls in there that are causing the CI to fail - List.filter_map and the like.

[Drup]

🎉 yay 🎉

Just to complement @Octachron 's presentation, there are two additional changes:

• Adding a new notion to the IR, "Alternatives", which allows to have different representation for the same thing. Currently, this is used for "a module expression or its expansion". HTML always uses the module expression, Latex and manpages choose according to the context. The manpage scheme for signature expansion was reimplemented with this in a cleaner way, and without changing the output at all, which is very encouraging.
  It opens the door for easily implementing things like "click to expand" or inline for module declarations in the HTML backend.
  Alternatives can also be used for other things, notably "ocaml or reason syntax" ....
• Removals of all the dl,dd,dt silliness. It's been a long standing discussion, I made an executive decision and pulled the trigger. All items have uniform markup now, with a div.

[Octachron]

I have restored the compatibility with 4.02.3.

[dbuenzli]

• Removals of all the dl,dd,dt silliness. It's been a long standing discussion, I made an executive decision and pulled the trigger. All items have uniform markup now, with a div.

Did you change the nesting structure along the way (I don't have the time to look into details right now but a quick look doesn't seem to indicate it's the case) ?

One of the problem with dl is that they are a pain to style because there's no wrapping element for a dt,dd pair.

IIRC what would be nice is to eave each structure item in its own <div> with sig and doc string segregated their own <div> and with the structure item being classified (type, value, etc.) on the wrapper div.

[Drup]

IIRC what would be nice is to eave each structure item in its own <div> with sig and doc string segregated their own <div> and with the structure item being classified (type, value, etc.) on the wrapper div.

This is how I intend it to be. I think I've achieved it but I would be happy to improve it further.

EDIT: here's an example of signature item with doc:

<div>
  <div class="spec value" id="val-bar">
    <a href="#val-bar" class="anchor"></a><code><span class="keyword">val</span> bar : unit</code>
  </div>
  <div>
    <p>
      foo bar
    </p>
  </div>
</div>

[dbuenzli]

That doesn't look too bad, except having the value on the wrapper div would widen the styling space while letting the inner div be easy to address (via value.spec in this case).

Unless you worry about space adding a doc on the docstring div would be nice aswell (so that you get e.g. value.doc if you want to do something fancy there, it also makes style sheets easier to read (e.g. .spec + .doc rather than .spec + div).

Also @trefis's markup had the id on the wrapping div this allowed to :target the item specification and comment for anchor highlighting.

[dbuenzli]

@Drup let's not discuss this there since it's unrelated. I'm interested in someone pinging me when the new markup stabilized so that I can update the odig stylesheets and maybe make a round of comments before it gets into the wild breaking again all stylesheets out there.

[jonludlam]

@Drup I presume you're happy with this, given you've been active in its development - in which case I don't see any barrier to merging this and doing any necessary tidying in master. Sound OK?

[Drup]

Sure!

[jonludlam]

@Octachron do you want to tidy this up before merging or shall I squash and merge?

[Octachron]

I would prefer to tidy up the history to at least split the document IR part from the latex-only part. (And keeping an independant commit for the -> ⇒ \rightarrow ligature is also probably a good idea).

[jonludlam]

OK, sounds good.

[Octachron]

Rebased and squashed down to three commits.

[jonludlam]

There's a failure in the tests in Recent_impl - it looks like there's an extra space been inserted into the expected output in your patch.

[Octachron]

Indeed, I forgot to run the test with a recent version of OCaml after fixing the rebasing conflicts. This should be fixed now.