Hello,
It’s my pleasure to announce the release 0.0.7 of odig. Odig is a command line tool to lookup documentation of installed OCaml packages.
Once it has made it to the repo, install with opam install ocaml-manual odig and consult the manual (or via odig doc odig).
This release provides support for odoc 2.0.0. The release notes have all the details.
Best,
Daniel
A big thanks to my sponsors. I welcome the new sponsor @joelb.
Thanks for the release!
Curious if there any plans to add a feature to odig to generate documentation for an opam switch in the manpage format? (as I understand odoc can do that). That would be very useful for those of us working on remote boxes through ssh.
Personally I don’t think manpages can do justice to the highly hyperlinked and cross referenced docsets the ocamldoc language produces. As a documentation author I find it a bit annoying that all my work (and the odoc dev’s hard linking work) gets destroyed by using such a poor documentation medium.
I’m wondering whether you considered using a text mode browser (.e.g emacs’ eww, w3m, etc.). For example:
BROWSER=w3m odig doc odig
Last time I checked odoc generated docsets worked quite well with it (and we should improve odoc generation if they don’t, because it likely also improves accessibility) and provided in my opinion a far better experience that a manpage could.
That being said if you really think the above is not satisfactory, it costs nothing to open an issue on odig. I won’t prioritize it but I might consider it when I review odoc's driving (which needs to be modernized to the new odoc ways of working).
This works surprisingly well, thank you! (I’ve never actually tried text web browsers before).
Though I’m still wondering if man pages could be better for lookups in API reference. I have a little util which searches through man pages with fzf and so I can quickly bring up the one I need. The lack of links between manages is annoying, I agree. Maybe info pages could be used instead as they have hyperlinks (though not sure how widespread they are outside of GNU)?
I tried it again after I posted and I actually quite like it :–)
You mean like lookup this function/type name ? In fact that’s something I would like to improve in odig both in the cli and in the web pages (along with bringing search in general).
Yes, exactly. Having something which can output a list of names, locations of definitions of those names in the documentation would be very useful for looking up with fzf or something like that.
Slightly related, for precise name lookups the problem should likely be solved at the odoc level. There is this old odoc issue which I wanted so that I could for example ask merlin for a fully qualified name in emacs and hook a bit of magic to open the odig generated docset in my browser at the right anchor.
That’s something I wanted too - effectively it’s just resolving a reference (i.e., a comment reference: {!Foo.Bar.baz}) on the command-line. It’s turns out to be pretty simple; I’ve had a prototype doing this before, so I’ve added it to the 2.1 project. A more complete implementation of search needs to be able to rank results, which will require tracking uses which we’re planning for 2.2.