ok, then maybe I can just indicate “Extensions” in that box, and move the “Reference” part to a less prominently displayed part of the doc page.
I don’t want to have to repeat myself here so here’s the link to the discussion on my comments in the issue.
Here is how the “Tutorial” pages look like:
and the “API” page (only for 4.09 for now):
I have not touched the other pages (tools, extensions, etc.) yet, so at this moment these only link to the relevent chapters on the INRIA website
I have added 4.10 to the github page for the Ocaml Tutorials:
In fact I have also added all other chapters, but there is no table of contents yet
(because the entry page should eventually be the ocaml.org documentation page)
The “OCaml API”, which is the documentation for the standard library, is now complete for all versions 4.00–4.10, with a quick search field, on the demo site:
that’s awesome! thank you a lot for your work!
An (even only approximate) support for searches by type signature would be nice!
good idea; I’ll think about it
@UnixJunkie, I have added type signature searching! does this sound good?
note: if you want to mix type signature and some keyword in the same search, you need to separate them with two spaces instead of one.
Ok, it does kind of work.
However, the list of results (especially their type signature portion) should be sorted by string distance to the type signature query; so that the ordering of results is more meaningful.
Also, if there are some exact matches, they could be highlighted in some way (like with a special background color or something).
there is already a sort by string distance (more precisely substring distance). Could you give me a specific example?
EDIT: for instance, in https://sanette.github.io/ocaml-api/4.10/index.html
if you type “int -> int” you see there is some kind of sorting.
I agree it can certainly be improved.
indeed the ranking algo was a bit buggy.
I just changed it. And implemented your suggestion to indicate exact matches
Pretty cool work! A couple of minor remarks I got from navigating the pages a bit:
- once we get to the docs for a specific version, I think it’s not very clear currently how to get back to the page with the list of all versions. My first attempt was to click on the big “ocaml” button, but it got me back to ocaml.org. The right solution is to click on the small link below (e.g “API version 4.10”). I think it could be made more visible; also, I find its name nonintuitive, granted that it makes me leave the 4.10 specific docs.
- I wonder whether modules such as
Obj, … should be hidden, or at least segregated to a special section. Also, I wonder why
Ocaml_operatorsis there since it just seems to be a piece of documentation. But maybe that’s something to report upstream. This page http://caml.inria.fr/pub/docs/manual-ocaml/stdlib.html seems to contain a “curated” list of the non-internal modules.
thanks for testing! some explanations concerning your points
- I completely agree; but 1) this page is eventually destined to be merged into ocaml.org 2) I was told that most users don’t want to switch versions often, so I thought of removing the “list of versions” page when merging into ocaml.org. Instead I’m thinking of a drop-down button to select the version.
- Again, I agree. Currently the “home” page is just the page http://caml.inria.fr/pub/docs/manual-ocaml/libref/index.html and the index is just build by parsing the file
(plus getting the type signature) because I wanted to stick to the existing manual. Maybe I should restrict to the “curated list”, as you said.
Ocaml_operators page, I added it because it is not so straightforward to link from the API part of the manual to the rest of the manual, and it is quite useful to be able to link to the precedence table in the description of an operator definition. It might make sense to rewrite the link to this page to the precedence table in the language reference chapter and remove the page altogether.
I have just processed the “Compiler API”:
So, I think that now the complete manual has been processed!
I will now work to integrate everything in the ocaml.org site.
Batteries would very welcome such a searchable OCaml documentation.
Our ocamldoc is here currently:
This is much better.
Thanks a lot, type searches are so useful!!!
There are various of suggestions on documentation of OCaml in past two or three years.
Problem is all of them need time & manpower, and only a few or nearly no one do them.