New styles for code examples in the OCaml reference manual

Ecosystem
1

I have recently restarted to play with alternative styles of the example displayed in the manual: for instance, core examples and advanced examples . I would be interested by any positive or negative feedbacks on the few styles available in the linked pages.

2

I know style is subjective, but for what its worth the very first style looks the most readable to me.

11%20PM

1 Like
3

I like the 3rd style: light blue rounded corner blocks containing both input and output.

However, I’m not fond of flexbox placing several examples next to each other. A line per example is clearer IMO (use width=100%).

1 Like
4

IMO styles 2,3, and 4 have to much distracting detail: rounded corners, dramatic shadows, 3D effects, etc.
How about a cleaner style with carefully chosen colors? For example, grey background (but no rounded corners or shadows) and good colors for the font.

2 Likes
5

I gave it a quick shot myself:
code

@import url('https://fonts.googleapis.com/css?family=Source+Code+Pro');

div.toplevel {
  padding: 1ex 1em;
  background-color: #333;
  font-family: 'Source Code Pro', monospace !important;
}

div.caml-input {
  color: #EEE;
}

div.caml-input::before {
  content: "#";
  color: lawngreen;
}

div.caml-output.ok {
  color: gold;
}

div.caml-output.error {
  color: red;
}
3 Likes
6

While I’m at it, here is another trivial improvement:

@import url('https://fonts.googleapis.com/css?family=Source+Code+Pro');

html {
  font-family: 'Open Sans';
}

div.toplevel {
  font-size: 10pt;
}

code
code.png908Ă—1073 117 KB

7

I have to agree with @smolkaj, but I wonder how much of that is because of familiarity (block with dark background for code). I’m not sure I like the open sans font though. I think serif font is better for large block of texts (I remember reading books with sans serif fonts and feeling slightly confused).

1 Like
8

FYI, there’s a pull request open right now where the author has done a nice job on CSS styling much of the manual. See: https://github.com/ocaml/ocaml/pull/1757

1 Like
9

Is the contrast with the text not a bit too strong with a dark background for the code examples?

2 Likes
10

I find the contrast a bit strong as well in @smolkaj s style . I like style #5 in the OP best, next is #1. The code boxes in https://github.com/ocaml/ocaml/pull/1757 are fine too, maybe better than all styles posted here, although I dislike the yellowish background used there.

11

I suppose it is a matter of taste. I personally find the strong contrast appealing, both because it makes it very easy to differentiate code from text, and because I’m used to reading code against dark backgrounds.

1 Like
12

Here is a version with equally simple styling, but a dark-on-light color scheme:

56
Screen Shot 2018-05-04 at 05.05.56.png1686Ă—1512 319 KB 

@import url('https://fonts.googleapis.com/css?family=Source+Code+Pro');

div.toplevel {
  padding: 1ex 1em;
  background-color: #EEE;
  font-family: 'Source Code Pro', monospace !important;
}

div.caml-input {
  color: #11A;
}

div.caml-input::before {
  content: "#";
  color: black;
}

div.caml-output.ok {
  color: green;
}

div.caml-output.error {
  color: red;
}
3 Likes
13

My personal subjective wishlist for OCaml manual / ocamldoc output / odoc output:

  • No custom fonts, only system font stack font-family: system
  • Light and Dark modes which can be switched easily
  • Big enough default font size
  • Non-wide layout so it is easier to scan lines.
  • ToC which is always visible and easy to navigate through

Updates:

  • Powerful search (inter-page and intra-page)
  • Obtain a link to a specific section of a page by clicking on the section’s header

Mode updates:

After second read, I think my message could come up as negative but I didn’t mean it to be so, I apologise. I really like the proposed designs (both in this discussion and in the linked PR to ocaml/ocaml). I just wanted to add more points to the discussion which I think are important.

1 Like
14
  • No custom fonts, only system font stack font-family: system

This. There is nothing specific about OCaml documentation that affects font choice, I can do that myself.

And I would argue that only the maximum width should be set: if I make my window narrower, I should not have to scroll horizontally. (Personally I would rather there were no width settings, just let me size my window myself, but I accept that I’m in the minority here.)

1 Like
15

Is it really necessary to add tracking cookies to google to display the manual? Depending on loading the font from google not only becomes expensive on mobile data plans, it also means the manual will display differently when you’re viewing it offline.
Bundling the font would prevent all of this.

3 Likes
16

Agreed on this. The style is good but the examples should not be next to each other.

That said…

  1. I also liked the “Terminal” style, though I wouldn’t say “Terminal” on top.
  2. As an easy initial step, the last style (with the left offset dotted border) seems like it would be quite non-controversial.

Also, @octachron, note that your simple and advanced examples are the same URL.

17

Also, I like @smolkaj’s style too. It’s nice and clean. We can use the gray offset background if we feel the black one is too extreme. I think this is probably the best of all so far, though I would recommend that we might eventually (eventually!) want to do Pygments-style code highlighting too, which should be fairly straightforward to add to the generation pipeline.

@bobbypriambodo, keep in mind that the “serif mono” style you like is a bit problematic for the following reason: because it just says “use monospace” in the CSS, all browsers are free to pick any monospace font they wish, not necessarily the serifed one you liked looking at. If we are to do this correctly, so that all readers get the same font. It would be good to find a specific serif monospace you like and specify it as a webfont.

19

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 (the example may not work with firefox currently).

(I also fixed the initial advanced example link)

2 Likes
20

I think @andreypopp s suggestion accomplishes readability in the sense that you describe. Too-wide lines are disallowed, narrower lines are ok if the browser window is extra-narrow. Possibly you misread?

21

@n4323, I totally misread what @jjb was suggesting, and angrily too! My apologies to all, and I’ve removed my reply. This should teach me both to be calmer about what I say and to read more carefully.