search

b0-system / odig

Lookup documentation of installed OCaml packages
http://erratique.ch/software/odig
Other
67 stars 6 forks source link

PDF support #73

Open patrick-nicodemus opened 6 months ago

patrick-nicodemus commented 6 months ago

Would it be possible for odig to generate pdf? I understand that odoc has the functionality to generate LaTeX.

dbuenzli commented 6 months ago

These kind of open ended requests are hard to answer. What would you like to see ? Besides could you point on where and how odoc handles latex.

(This won't happen immediately and odig odoc's driver is pending a rewrite. But given enough design hints I could try to cook up something for when this will happen)

patrick-nicodemus commented 6 months ago

Sorry I don't know much about odoc, I was hoping you might know. It was listed in the GitHub page.

https://github.com/ocaml/odoc

I will talk about the motivation behind my request. I tried to help someone get set up with OCaml recently. They use Windows and we had difficulty with the DKML installer so we switched to WSL. This worked well but now odig is difficult to configure because the user has to understand how to configure WSL to have Windows to launch a web browser by setting the BROWSER environment variable or setting the xdg browser related settings. Maybe I am wrong about this but it seems tricky. There is documentation available on OCaml.org/p/xyz but I have repeatedly had problems with that site being very slow and I would really like to find a way of easily navigating local documentation.

So, I can directly open a web browser in Windows and point it at the html files in the Linux filesystem in the opam cache and this is workable. This is fine and works but is somewhat trickier for a student who doesn't have experience with all these technologies (day 1 with the OCaml platform, new to utop and dune and ocaml-format etc.) and now has to remember this filepath to the documentation.

So this is kind of an XY problem where the real question is what can be done to make odig easily usable by WSL users. Making a PDF was just an idea I had because PDFs are more self contained than html files that need css/js alongside, the PDF can be copied into some convenient document library or ebook reader away from the opam cache so users don't have to remember the files are in the opam cache.

I apologize for the open endedness of the request I just want to find a good way to make the documentation more accessible to WSL users.

patrick-nicodemus commented 6 months ago

Btw on my machine when I use wsl odig "just works" with no explicit configuration and windows opens a browser to the files when I run odig doc. But this didn't work for the person I was helping and I didn't know how to do the configuration.

dbuenzli commented 6 months ago

Honestly I don't think PDF is such a great medium for working with API documentation.

Now it seems to work for you, so that doesn't seem impossible.

First, you should perhaps check the actual invocation odig uses on your machine and theirs by invoking it with odig doc -v -v to see the differences.

Second there have been issues on windows with the underlying browser launching code which lives in the b0 project. The discussion seems to have stalled, I'd be happy to resolve the matter. So do not hesitate to follow up there.