Well, after some thought, I beleive, in fact, that this is doable. At least, for “modernizing” the online manual, I think that post-processing the html is finally the best solution. Not ideal, of course, because the way the html was produced could change over time, but considering the complexity of the complete tool chain for producing the manual, hacking the final html is both the easiest for the hacker (me), and also the less effort the others interevening at various stages (they don’t have to change their habits).
1 Like
I found some time to work on the first part of the Manual. This is the part I’d like to call “The tutorials”.
What I have done:
- post-processed the html files with an ocaml script. Huge thanks to the great
lambdasoup! - added syntax highlighting. Thanks
higlo!! - wrote CSS based on
udoc.css. Trying to be consistent with theocaml.orggraphics charter; but improvements are welcome, of course. - I took the liberty to change the word ‘chapter’ to ‘tutorial’ everywhere; this sounds more inviting and less ‘academic’ to me. Other than this, the text is unchanged.
The current result is here:
https://sanette.github.io/ocaml-tutorial/core_tutorial.html
The source is here, and can be used to discuss issues: https://github.com/sanette/ocaml-tutorial
12 Likes
This looks nice. 
Looking at the comments here, I’m rather surprised nobody suggested using tools like wkhtmltopdf or Apache’s fop. (Apart from OP who arrived at the idea of converting the HTML docs to PDF).
Is introducing such battle-hardened and veteran specialised tools frowned upon? Or is there no source material for fop (which requires an XML and processing instructions)?
Right, I thought about this too; the first thing would be to write a good print.css
Yep. Erlang’s PDF docs for example are an optional build step that depends on certain Java versions and the presence of fop. If it can’t find suitable Java or fop, it just doesn’t build the PDF docs and the build finishes without the installation having those offline PDF docs.
The manual source are currently in Latex. We have no trouble at all building pdf (with correct cross-references), so I am not sure how a html-to-pdf tool is relevant.
While I am at it, @sanette, it is useful to keep in mind that post-processing the html manual is perfectly fine for a mockup, but probably not for deployment. You should also have a look at the manual license. You probably need to add at the very least one link to the canonical manual.
with all respects, I don’t agree. My guess is that if it’s not done in an easy way like this, it will never be done at all. I can be wrong (hopefully), but I don’t want to wait forever for a proof.
1 Like
oh yes of course, thanks for the reminder. I just did it.
The licence also says that the authors should be contacted. Do you want me to do this? On the other hand, since the goal is to move these pages to ocaml.org, it probably makes more sense that the maintainers of that site contact the authors.
Once you have a final version, it will be necessary have a more formal consultation for the publication on ocaml.org.
However, experimentations are fine with the derivative part of the license (at least @xavierleroy agrees with this interpretation) .
You imagine that I am not exactly thrilled when you are proposing to complexify my job as one of the maintainer of the OCaml manual because it makes development easier for you.
I still think that the best course is that you keep experimenting with technologies that you are familiar with. And at the end, we will have look to see if it is really needed to add one more layer at the top of the manual pipeline or if I can backport the relevant features lower in the pipeline.
I think there is a misunderstanding; of course I don’t want to give people more work; this is precisely why I propose my help. The main point is: do we want to integrate a modernized version of the manual in ocaml.org, for the benefit of the community and for popularizing the language? – and making the website look better.
My impression is that many people in this list are pushing for a yes, because we find it too bad that ocaml is not more popular. The creation of the Ocaml Fundation goes in a similar way. I know, it means, at some point, to do some work.
From what I saw, generating to manual is not so obvious. My second impression is that generating a nice web page is easier to do from the html, and will give less work to all of us. In fact, as a maintainer of the ocaml manual, you will have nothing to do! I did this precisely because I know people are reluctant to change their workflow (everybody’s time is precious, I know!). The ocaml manual will stay as it is, latex+pdf+html, located at INRIA.
I just proposed to host a modified version of the manual on ocaml.org. This will effect the maintainers of that site, of course; but can I propose my help. I’m confident that running the script to generate the new manual should not give rise to too much maintenance, based on the fact that Hevea is in a very stable state, and hence quite reliable.
In your answer, two points worry me
- how long before someone takes a decision? If several years, then forget it, because trends move fast, and what we are trying to achieve now will be outdated
- keep experimenting… well I’m ok up to a certain point
I have nothing to gain here, I’m just trying to make things better on my free (? is it really?) time.
1 Like
If you put together a decent PR and submit it to the repo, not very. GitHub - ocaml/ocaml.org: The official OCaml website.
I had some issues with how the manual used to look like (i.e. this) and I submitted some PRs to improve the build process and the CSS (which were promptly overwritten by somebody else’s CSS 
). Didn’t take long for them to get merged.
1 Like
@steinuil thanks for the information. I haven’t touched that part yet. I suppose I first need to have a running local copy of the ocaml.org web site? I have to learn how to do this…
Well, nowadays I am also often doing the update for new releases on ocaml.org. So no, I will still be doing a little bit more work, probably. And anyway, it is simply not an option to tell me to just not care about the state of the manual on ocaml.org .
This is an interesting observation! At which step did you fail when trying to generate the manual? Which points of the readme was not clear and should be improved?
For prototyping certainly. On the long term, I am not convinced? Doing minor html structure transformation can be done without troubles, same as updating the css. Highlighting or major html change is more involved certainly. And some glue code would probably be needed for the integration in ocaml.org anyway.
Integrating the manual on ocaml.org is certainly an important goal, modernizing the manual could be nice.
I am not sure what is worrying you here? The version you posted was just a draft, isn’t it? At some point, it would need to be reviewed being published.
I understand from the discussion that you (@sanette) have some reluctance to touch the bowels of the manual-generation, both from a technical and from a how-open-are-those-people-to-external-contributions point of view. I can understand where that comes from, and I think it is partly correct and party a misinterpretation.
Yes, some parts of the manual build are old and arcane (hevea, the latex->HTML tool for example), and of course we’re not expecting external contributors to jump into their implementation to propose changes. But building the manual should be fairly easy and is well documented, and contributing to it is a fairly simple process (send a pull request following the usual process, including having a look at the CONTRIBUTING document first).
I agree with the general position of @octachron in this discussion that for a prototype/experiment, you should feel free to use whichever tool you want, but that as soon as your work as stabilized we should try to think about whether some parts of the work can be upstreamed to the direct build, instead of staying an experiment-grade post-processing layer that we would have, in practice, to keep up-to-date and maintain indefinitely. Note:
- I’m not implying that you should do the work of upstreaming the changes, although your contributions are of course welcome. @octachron has of late been our most active contributor to the quality of the OCaml manual, and I’m sure he would be happy to help within time available, others may be as well.
- We may decide to keep some amount of post-processing in the long-term state, if it is too costly (in terms of time, expertise, or availability of the people with the expertise) to integrate certain steps in the build process; and there could be a gradual transition. But from a “maintenance for the next N years” perspective, I think it’s important to make justified decisions for what goes where in the pipeline.
You come as relatively-new contributor, and you experience usability barriers that many of us don’t see anymore out of habit. Thanks for going through this to improve the manual! I hope that you’re going to find out that the situation is better than you think, and that the work will be better as a result of making an extra effort to interact well with the upstream.
3 Likes
hi @gasche, thanks for your post. I have to admit I was surprised by some aggressive tone. But of course I understand that it’s natural to react against “newbies who know nothing and want to change everything” 
Concerning the (necessary) discussion about technology, what I can say right now is the following. I didn’t choose lambdasoup and higlo because I was familiar with them. In fact, I had never heard of them before last week. But after thinking about the whole process (from pre-LaTeX to website), my conclusion was that it would be difficult to obtain a reasonable website (with, for instance, a fixed column on the left with the table of contents) using hevea alone. Rather than trying to develop plugins for LaTeX/hevea, it sounds safer to instead rely on the stable nature of these tools (hence, a stable produced html that can be post-processed.)
Don’t underestimate the turing completeness of CSS ;–) The odig stylesheets for the manual do this (unless your window is too narrow) without touching the HTML output at all.
The column is on the right and I didn’t fix it but it’s a few CSS selector away if that’s your thing. See here for an example and follow this link for the actual stylesheet
That’s not to say there are not a few things that could be improved upstream for better classification to simplify the CSS selectors of these stylesheets (some are quite horrendous) but I don’t think there’s anything wrong with the upstream technology.
In particular I don’t think LaTeX and HeVeA are arcane. As far as I remember using the latter for the ocamlunix book work it’s a pretty good piece of technology once you take the appropriate steps to make it generate good css classifers for your LaTeX environments (e.g. see the prelude.hva file here which replaces the corresponing prelude.sty for the PDF).
@dbuenzli, that css is impressive indeed.
But don’t you think that such involved css selectors as the ones you mention rely heavily on the way the html was produced? (and hence could be a problem against a new version of the manual?)
In some sense, what I did with lambdasoup is actually similar (works with css selectors) with the additional benefit of a real programming language (in my experience of making websites, the css part was always the most frustrating and time consuming; even with some nice preprocessors like sass).
But if there is an agreement on not to use it, I won’t insist.
As you said, if the css could be simplified by adding some suitable classes that could be a good idea. I have nothing against LaTeX (use it all the time). Of course it was not made for producing websites, but why not
For syntax highlighting, then instead of using higlo it would mean doing it in the LaTeX source, there are some packages for it. There was some discussion on the github page about it.
Sure, and that’s why I think upstream should be worked on to improve it along the lines I suggested.
But on the other hand, as far as deployment goes, working at the css level doesn’t require much: just drop a css file.
LaTeX is certainly not arcane if used properly. It’s just an OCaml manual that doesn’t use many of the LaTeX cool features. @sanette for the syntax highlighting so far the best options are minted or listing packages, see #8718.
For example something like
\begin{minted}[fontsize=\small]{ocaml}
let rec factorial n =
if n = 0 then 1
else n * factorial (n-1)
List.map (fun x -> x * 2) [1; 2; 3]
\end{minted}
The tools for LaTeX are evolving, for example next generation of it - LaTeX3 is being actively developed on GitHub, LaTeX LSP server (Language Server Protocol implementation) in Rust is all rage, there are efforts to rewrite TeX in Rust completely, based on the Tectonic project of user-friendly TeX distribution.
3 Likes