May 2018 OCaml DocJam Log

This topic is intended to collect a log of what people have done during the May 2018 DocJam.

If you have done a task as part of the DocJam (sending a pull request with a proposed documentation change, written a new wiki page, published a documenting blog post, etc.), please post a summary here of the task, with hopefully a link to see the work. It will be very nice, after the Jam is done, to have an idea of what was collectively accomplished.

For example, the following format is just fine:

I just finished working on X for project Y, with help from Z and a review from Z’.

For free-form discussions about the DocJam, please use the DocJam discussion thread instead.

1 Like

Just a shoutout from me that I am working on a tutorial on monadic parsers and Angstrom in particular, as part of the Ocamlverse project. Expect the first draft, hopefully later today.

I was wondering if, as part of the effort, someone could have a look at @steinuil’s pull request to simplify and speed up the build process for the main manual:

It will make iterating on fixes to the manual during work this weekend less burdensome.

This is on my todo list, but if a makefile expert wish to review, they would be welcome.

1 Like

Here is the draft to my tutorial on monadic parsers and Angstrom. If I had this 2 months ago, lots of pain would have been avoided. All critique is very welcome. @ivg already reviewed the part on monads and he’ll send me some corrections later. I don’t know where is the proper place to discuss things like this? Github? Or maybe here? Create a new thread for this tutorial?

Here it is:

In the section about infix operators, the manual page you point to is from the caml-light manual (the predecessor of OCaml). I think the corresponding pointers in the current manual should be and/or the table at the beginning of (did not find an anchor).

Admittedly this is indeed buried in the manual and should maybe deserve its own section.

1 Like

I would appreciate if it was possible to keep the discussion about what is being done and comments on what people write to other threads, so that it is easy to browse this thread to see a log of actual, concrete actions. The DocJam discussion thread should be appropriate for everything else, and yes, please feel free to open a new thread for multi-message discussions of any particular docjam-related topic.

1 Like

Do you think you could post perhaps a full explanation of the process you’re expecting? That way we know the full thing.

BTW, there’s a bunch of people discussing the docjam on both irc and discord, so those might be good places to hop on to to herd the cats. :slight_smile:

So far, I’ve produced a quite skeletal Guide to PPX Extensions with some help from the folks on IRC. It certainly isn’t anywhere near finished, but help would be greatly appreciated.

1 Like

Currently the Menhir manual is only available as a PDF, which is sometimes a bit annoying. I wrote and submitted a pull request that introduces a HTML rendering of the manual, using Hevea for LaTeX-to-HTML conversion (I tried other tools and they were much worse). You can see the current HTML output, which is inspired by the new styles recently proposed for the OCaml manual.


This was a very good idea! One aside, though, the x-heights of the fonts you are using don’t seem very compatible (the monospace is too small, the sans serif too large), so you might want to adjust their sizes so that the x-heights match:


Anyway, thank you so much for this!

I’ve been too busy so I was unable to do any substantial work, but I managed to create a PR to reorganize the Tutorials page on Hopefully it would make it easier to people new to the language.

1 Like

When I worked on the Menhir manual yesterday, I had to fix a minor rendering glitch that may be a Hevea bug (I’m not sure), so I just created a small repro case and sent a bug report on the just-created git repository: maranget/hevea#1, “Hevea spacing of tabbing looks wrong”.

1 Like

I worked on moving the quoted strings syntax to the main part of the reference manual: .
It felt a bit frustrating that there is no part in the tutorial dedicated to strings, thus the example in the tutorial is very minimalist.


I also decided to propose to switch the reference manual to utf-8: .
Because, I may have tried to replace “Hello world” by “Hello :earth_asia:” in the PR above.


I’ve heard people complain that Alcotest’s filters are not documented, so I submitted this PR to improve it: alcotest#133. While doing that I discovered and fixed a bug where some error messages got lost because OCaml’s stderr formatter is not flushed on exit.


I have been working on visual improvements to the documentation generated by odoc. Here’s the link to the official PR that describes the changes in detail. Here’s how it looks on a demo package:

If you have any suggestions or ideas, please let me know!


Very very nice work! I’ll contact you privately with some suggestions for the CSS.

1 Like

@rizo That looks so good!

1 Like

That looks great! Awesome work :slight_smile:

1 Like