That said, I’d like to emphasize strongly: I think we should do this in steps. Git commits are inexpensive. Lets clean up the CSS bit by bit, add features in small steps. Add the CSS now, add klipse when someone has the time for that, etc. That way,
People get immediate benefit from an improvement to the manual rather than having to wait for all the possible improvements to happen as part of a large project.
We get to see that we’re making mistakes before we proceed too far down some path.
Having looked at everything on offer, I think I’d like to support this suggestion for now, that is, @smolkaj’s CSS style for program text on very light grey background.
Ah, I was talking about the manual text, not the monospaced code. The second change by smolkaj changed the body font to Fira Sans, and I prefer to keep it serif as is. Unless I misunderstood you?
No, I misunderstood you! He also picked “Source Code Pro” for the examples, which I support if only because it means we’ve selected a font for consistency, but you weren’t talking about that. And I agree with using serif fonts for the body text.
I do think we should switch the body font to a specifically selected one, rather than leaving it to the mercy of whatever random font the browser has. I’ve proposed EB Garamond, which is probably the best available open serif font.
I’d like to use Fira Sans, but only for headings. And we need to pick a font for the example code, and Source Code Pro is pretty good for that.
I think that it could be nice to go directly to interactive examples using klipse, as it was suggested by @viebel for the OCaml site. It would need a bit more of integration work to perform flawlessly; but at basic mode does not require much meddling: For instance: example
This worked for me in Firefox.
It does depend on something at cloudflare.com as wells as something on google.com for it to do anything, though. This is useless in a manual for offline use.
I’ve been happy to let others speak, because everything I would say, someone else has said. However, I react strongly to putting the code on a black background. I understand that I am unusual in that I set my text editors and terminal windows to have a light background, but still–the manual is like a book. Books don’t have black backgrounds (usually). If the code is in black background, and the rest of the text has a light background, it feels like a kind of noticeable perceptual shift is required to go from one to the other.
I don’t mind the light gray background.
Anyway, those are my feelings, fwiw.
(It’s true that I have been running discord with the dark background. That’s because the light background scheme doesn’t have enough contrast on some of my devices. Note that the dark background is not black; it’s just a dark gray. However, I’m not sure that would be a good choice for manuals.)
I’m a little bit worried that embedded klipse will end up seeming overengineered, and will cause problems in some unforeseen situation even if it’s only on conditionally, but that’s just a vague worry. I don’t know.
@perry I think just putting the javascript and fonts and things in the local distribution (instead of inserting external references) will solve the problem.
I would just really implore you to experiment with going that route, since I do see a lot of value in editable examples - and while I’m a lowly geek with lacking aesthetic sense other people tell me that fonts are important - but I think it would be such a shame to have a manual that acts differently depending on whether or not you are connected to the internet.
At least I find it easier to learn something when I don’t have the internet to distract me.
A number of people seem to be concerned about our using a CDN for fonts. It’s straightforward for us to package the fonts with the site and serve them ourselves if we wish.
Under those circumstances, if we find we want a CDN to improve performance, we could always use CloudFlare or some such and CDN the entire site, though someone would probably end up having to pay for it.
I will also point out that if you install the given fonts locally on your system, your browser will use the local versions and won’t bother downloading them.
Whatever you do please ensure that opam install ocaml-manual allows to read the manual without having to fire a webserver locally on your machine or needing network access.
@dbuenzli I think that’s a reasonable requirement. The question is whether you would get the same fonts or not. I think there are enough people demanding it that it will probably be necessary to have the fonts bundled with the html.
Note that initially when I did the odoc stylesheet I did use custom fonts. Some reviewer complained to me (I don’t remember exactly what for, waste of resources maybe) so I eventually removed them and falled back on web safe fonts.
I’m not fundamentally against custom fonts but it should perfectly be possible to improve the manual without resorting to custom fonts
(see e.g., https://ocaml.github.io/ocamlunix/ for a hevea produced document that looks a bit less from the 90; not that this could get some improvements – e.g. responsive font sizing – this was made 9 years ago).
One can indeed improve it without custom fonts, but custom fonts make it much nicer. The default fonts in many browsers are not very good.
Anyway, if I’ve learned one thing about the OCaml community, it is that it will not be possible to please absolutely everyone. I think we should try to be as reasonable as we can for people with various concerns while (in the long run) not compromising readability.
@perry I can’t load anything from behind cloudflare without having to solve five captchas (for the benefit of US warfare, even, according to recent reports - https://www.vegard.net/google-helps-pentagon-train-killer-drones/ ).
I’m surprised to see my almost violent reactions to this web browsing experience; it gets extremely frustrating very quickly. I will celebrate the joyous day CloudFlare goes bankrupt.
Today I’ve given up on reading things behind CloudFlare, and I would hate the OCaml documentation to be one of the things on this boycott list, since I quite often need to look up things in the documentation. Please don’t put it behind CloudFlare.
EDIT: Note that I’m all for custom fonts, I just think they should be distributed with the html, making it work the same without online access.
Then I suppose you might build the docs locally if we do that, as it would solve that problem. It’s literally impossible to please everyone. Someone will have to deal with a bit of inconvenience, like building their own local copy. If we find ourselves DDoSed or what have you, CloudFlare or an equivalent may be necessary, and you would have that alternative.
It does indeed seem quite early for that, but @cfcs insisted on telling us in advance never to do it, and so I explained to him, in advance, that not everyone always gets what they want, and who knows what might become necessary in the future.
