You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Has there been any interest in converting the manual to odoc? It seems not particularly contributor-friendly to have it require LaTeX and hevea. Plus then it'd be dogfooding OCaml's own documentation tooling. And it'd be pretty easy to add search to the manual.
We don't actually require manual contributors to install Hevea. They can look at the PDF output for the reference manual, and at the HTML output of the stdlib documentation (make html_doc). We could clarify this in the documentation if you think this is a useful change.
There are a lot of things that the current manual build can do, which are not supported in odoc's markup language. (For example we have macros to run examples and include the toplevel output. More basically, footnotes.)
odoc is designed as a convenient tool for API documentation and lightweight documentation webpages, while the reference manual is thought as a full online book. Bridging this gap requires either reducing the quality of the reference manual output, or pouring a substantial amount of work into odoc to make it book-capable -- if we decided that this was a worthy design goal, which is unclear to me, there are probably enough specialized markup languages for advanced content production (LaTeX, docbook, someday Typst, etc.).
Note: I do agree that improving odoc benefits everyone in the OCaml community and is therefore a worthy goal. But I don't think we can reasonably expect the people who contribute to the OCaml reference manual to do this work, because those people are few and far between -- the manual sees maybe a human-week of work every year.
@sanette had implemented search in his own custom overlay over the stdlib API documentation (see discussion thread from 2019), so it is probably doable to do this for the reference manual as well -- indexing the text after HTML rendering, I suppose.
(I'm not sure I would decide to invest time in this myself, given that the manual is already indexed by search engines, for example the Google search site:ocaml.org/manual inline records seems to work just fine. Is providing a local, custom search engine over the manual text something that would really make a difference for users?)
Yes, I think it would make a difference. Being able to search for items in the docs while reading is quite helpful. And not every user may know about Google's site: feature
For indexing the part of the manual which is not the API, I think https://pagefind.app/ could help. I've add good results deploying it on top of an existing documentation in which the search was pretty poor. And it's really simple to setup, from a practical standpoint.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
-
Has there been any interest in converting the manual to odoc? It seems not particularly contributor-friendly to have it require LaTeX and hevea. Plus then it'd be dogfooding OCaml's own documentation tooling. And it'd be pretty easy to add search to the manual.
Beta Was this translation helpful? Give feedback.
All reactions