Build latex files with the `@doc` alias

[giltho]

Hi!

This PR aims at adding a _latex target to the @doc standard alias. There is no open issue containing the word latex so I thought I might just as well write a PR to get the discussion going.

It's still a work in progress for several reasons:

• I'm not very familiar with the inner workings of Dune, so there's probably a lot to improve
• The latex macros are hardcoded in the toplevel file, and extracted from the main ocaml repo. It would be nice to be able to generate a sty file the same way highlight.pack.js and odoc.css are generated, using some odoc support-files command
• For a package name some-thing, odoc generates a file called some_thing, I use Re to replace every - into an _ but I'm not sure that's the best thing to do
• Importantly, files that are produced by mld files are correctly generated, but they won't appear in any pdf document, because they're not \input in any latex file accessible from the toplevel file.
• Various classic latex issues like cross-referencing bugs.

I tried to factor out as much as the common logic between html and latex as possible, but I'm not sure if of how well I did that. One thing is that I'm really not satisfied with the following functor names Generator_setup, Generator_helper, Html_setup, Latex_setup, Html_generator and Latex_generator.

Additionally, here, or in a subsequent PR, it would be nice to have a stanza in the dune-project file that explains how to call some kind of latex command to build the latex manual as an option

Any early feedback would be helpful :) In parallel I'll try to improve the latex story on odoc's side, in particular, trying to make progress on https://github.com/ocaml/odoc/issues/123

PS: as a bonus, there's a tiny "fix". The usage of List.filter_map was unnecessary. Looks like the legacy of some previous version where there was something to filter

[nojb]

This PR aims at adding a _latex target to the @doc standard alias. There is no open issue containing the word latex so I thought I might just as well write a PR to get the discussion going.

Apologies, could you explain a bit more what you are proposing on this PR? Are you adding a new built-in alias to generate LaTeX? Are you modifying the existing @doc alias to generate LaTeX in addition to the HTML? Or something else? What is the _latex target you mention?

In general it seems sensible to support other output formats support by odoc apart from HTML.

[giltho]

Yes, sorry the wording was unclear I am modifying the @doc alias to also generate LaTeX in addition to the HTML, it will be built in a _latex folder next to the_html folder.

[bobot]

Note from meeting:

• can't be be for dune 3.0 -> so 3.1 at least
• restrict the feature to 3.1 and above
• don't change the @doc alias @doc_latex
• use directory target

[mndrix]

Once this solidifies a bit, I'd like to submit a separate pull request to add a @doc_man alias to generate man pages.

[giltho]

I'm not really sure where to restrict the feature to dune > 3.1, where should I be adding a guard? In the gen_rules function?

[giltho]

Additionally, I'm trying to get things to work using directory targets, but I get

File "_doc/_html/scope1/_unknown_", line 1, characters 0-0:
Error: Rules with directory targets must be sandboxed.

Is there something specific I should be doing with directory targets?

[bobot]

In the gen_rules function?

It is the easiest place. Features that have a specific stanza are restricted at parsing time, it is more static. But here since there is only an alias; gen_rules it is. Usually I like to have nice message for < 3.1 but I'm afraid to break people that already uses an @doc_latex alias., so you just have to bind the alias only for >= 3.1.

Is there something specific I should be doing with directory targets?

You should specify that the action with the directory target is sandoxed.

[giltho]

Update: I had a very intense deadline the past week and was not able to work on that for a while, I apologise I did make some progress locally although I'm a bit stuck on some things, but I'm setting some time this week to finish this PR properly.

[giltho]

I've made some progress but I'm stuck with mainly one thing at the moment, odoc doesn't handle html and latex generation the same way:

• For html, it generates folders for each lib in a package, i.e. you'll get pkg/Lib/index.html for each lib. That means, for a given lib, I can consider pkg/Lib to be a directory target.
• For latex, it generates a bunch of file called pkg/Lib.Module.texin the package folder. Because one package may have several libs, I can't consider that entire folder pkg is a target, and I don't know in advance the list of files it's going to create. There is only 1 file that I know will get created, which is pkg/Lib.tex for a give lib. I can choose this as a hidden target, but if I do, activating sandboxing will break the build, because that's the only file that will be kept.

Should I just choose use no_sandboxing or is there a better solution?

[Alizter]

If it's any consolation, we went with @doc-latex for the analogous feature for Coq using coqdoc implemented in #3760.

[Alizter]

I have https://github.com/ocaml/dune/pull/6778 if you want to use that alias.

[Alizter]

Marking as draft since it is still in progress.

[rgrinberg]

Please re-open if this is still relevant