@perry If the parts required to render the manual are bundled with the manual, I can indeed run my mirror on github pages, or just read the docs locally. If the docs depend on resources from CloudFlare and Google, that will be harder. That’s the point I’m trying to make.
RE: DDoS mitigation: Color me surprised the day our archenemies in the dynamically typed language camp decides to instigate a Blitzkrieg through the use of … DDoS on our manual pages.
Excellent news!
Which parts were done though? The stuff for the main part of the manual was quite baked, but the stuff for /libref/ wasn’t workable yet I thought. But I’ll look at the merge.
And I already said that we were doing that because there was strong demand for it, and that something like CloudFlare would be a possible mitigation if and only if we found ourselves with load problems at some point in the future, and then you complained loudly about CloudFlare.
BTW, I’ve seen web sites for flower arranging DDoSed. I’ve seen web sites for discussions about mystery novels DDoSed. People do insane things.
How does it work for people in countries where google or cloudflare are blocked or for people using tor?
We already said that the consensus was to self-host the fonts, and the commit done today self hosts them. As for CloudFlare, read what context that was brought up in, and please read carefully.
I read carefully. Thanks for patronizing me.
Then you are aware that your concern is with something that is not under consideration and was mentioned in a different and entirely theoretical context, and presumably you are no longer worried about it. We can therefore move on.
Personally, I think Rust’s std API manual with the light theme chosen (use the little paint brush at the top left) is quite readable. It’s similar in style to this Discourse forum: the fonts chosen are fairly readable, and the colors for syntax highlighting are relatively unobtrusive (although they might be a bit too low contrast for people who are color blind). Perhaps we could borrow some of their styles?
They’re not our archenemies. Don’t worry about F#, either. OCaml should get so popular that Java devotees come after us.
So one of the things we might want to do, since passions seem to run high on things like fonts and colors, is to let people choose between several themes. If you are good at web front end stuff, I suspect a pull request to make that possible might be welcome.
Some of the newly proposed manual styles have a problem with documentation of constructors in sum/variant type declarations, that forces the parameters of the constructor to line-wrap instead of having the constructor documentation wrap. At the time of writing (although it may change in the future as the URL is not stable), http://preview_docs.narwhal.space/libref/Arg.html has this problem that shows clearly in the spec documentation. Compare with the rendering of the current manual where most constructor datatypes fit in one line.
Would it be possible to tweak the CSS of these code classes so that the documentation column typefieldcomment if I read it correctly wraps, instead of the constructor or type parameters fields? (Those don’t have a class of their own for now, but they are first and second <td/> in <table class="typetable"/> elements.)
The current manual version wraps, too, if the font size is large. The difference is that in the current manual, the margins go to the edge of the browser window, so that if you shrink the font size, it stops wrapping because there are more characters per line. The new style has a fixed number of characters per line, or something like that.
I don’t think it’s a difference in the kind of font sizing it’s using, but the fact that it’s a smaller page. If you view the current manual in a narrow window this happens too.
One fix is td code { white-space: nowrap } which looks much better on large screens but forces content outside the page on small screens. We could do an @media rule to address this.
I was working on this very issue in my own changes to the reference manual. I couldn’t get it to work without editing the html, but perhaps someone else would be good enough to do it. If we do need to change the html, some corresponding changes to ocamldoc will be needed.
BTW, in general, tables like the one @gasche is complaining about seem to be quite badly rendered in both the old and new versions of the manual. Cleaning this up would be a good next step in the manual overhaul. I’m not sure we should be using HTML tables for this, FWIW, as CSS has alternatives.
Tables are reasonable for this kind of thing; the Racket docs use a table for syntax definitions as well, but they use monospaced fonts so that they know exactly how long each line will be, and properly indent the terms as part of generating the html output (which I don’t think is humanly possible to implement in Latex). I’m not sure CSS can help much with this.
Just to note, the part of the documentation in question is generated by ocamldoc, not LaTeX, so we have more control.
Just to clarify, changing ocamldoc to improve the rendering is just fine – at least as long as we only add extra classes as desired, so that user-defined styles keep working. Completely changing the HTML structure is possible but requires some thought for users.
Or we could have multiple modes to retain backward compatibility while allowing new html and class structure for those specifically requesting it.