May 2018 OCaml DocJam Log

Community
1

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
2

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.

3

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: https://github.com/ocaml/ocaml/pull/1781

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

4

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

1 Like
5

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: https://github.com/loxs/ocamlverse.github.io/blob/master/learning/monadic-parsers-angstrom.md

6

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 http://caml.inria.fr/pub/docs/manual-ocaml/lex.html#sec82 and/or the table at the beginning of http://caml.inria.fr/pub/docs/manual-ocaml/expr.html (did not find an anchor).

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

1 Like
7

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
8

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:

9

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
10

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.

8 Likes
11

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:

image

Anyway, thank you so much for this!

12

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 ocaml.org. Hopefully it would make it easier to people new to the language.

1 Like
13

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
14

I worked on moving the quoted strings syntax to the main part of the reference manual: https://github.com/ocaml/ocaml/pull/1788 .
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.

2 Likes
15

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

2 Likes
16

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.

6 Likes
17

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: http://odis.io/odoc-demo/order/Order/.

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

14 Likes
18

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

1 Like
19

@rizo That looks so good!

1 Like
20

That looks great! Awesome work :slight_smile:

1 Like