Better differentiate between kinds of code samples

[cuihtlauac]

It's been raised by @christinerose when reviewing documentation that it isn't easy to make the difference between the various kinds of code samples found in markdown documents.

Today, we are mainly using using two:

```ocaml
```ocamltop

However, there are more cases

• Hash and double semicolumn stuff
  • standalone top-level expression
  • top-level expression with environment references
• w/o hash and double semicolumn
  • valid code sample, which may be copied into the top-level
  • valid code sample with many references, which shouldn't be copied into the top level
  • pseudo code, which must not be copied in the top-level

We need to devise a better way to handle this.

Edit:

Additional input in the same lines from @Tchou, #950 (comment):

• w.r.t to code examples, it's ok to give code that, in isolation, does not compile (e.g. because some value is not defined because it was defined three examples above) but syntactically incorrect code such as val Option.map : … will be confusing for beginners that will try to cut and paste it. Maybe in such case, not use a code formatting box but just some tt font ?

[sabine]

IMO the long term direction here involves playground integration.

Short term fixes probably involve changing the design to
(1) make these two different kinds of code examples more obvious to distinguish, and
(2) number split code examples, e.g. 1.1, 1.2, 1.3 or 1/3, 2/3, 3/3 so that people know they have to be entered in sequence and when to expect an interesting outcome.

This will be very interesting to explore with Claire.

[cuihtlauac]

IMO the long term direction here involves playground integration.

Using the playground should definitely be an option. But integration with tools should be considered too.

(1) make these two different kinds of code examples more obvious to distinguish, and

Maybe they could be rendered differently? Black background for top-level stuff (terminal-like experience) and white background for the rest (editor-like experience)

[christinerose]

IMO the long term direction here involves playground integration.

Using the playground should definitely be an option. But integration with tools should be considered too.

(1) make these two different kinds of code examples more obvious to distinguish, and

Maybe they could be rendered differently? Black background for top-level stuff (terminal-like experience) and white background for the rest (editor-like experience)

I definitely love the idea of a visual difference like this!

[gpetiot]

Taken from #1150:

Currently the same style is used whether the code is:

• OCaml implementation
• OCaml interface (.mli)
• REPL

To make it clear whether the user should copy/paste the code in utop or in their editor it would be handy to have a different rendering for these blocks (could be something CSS based, or a caption for the codeblock, etc.).

This might not be obvious for beginners that if a snippet starts with # it belongs in the REPL and might be followed by the output or errors. Same for type signatures/module signatures/etc that should either belong in a .mli file, or are given for reference, but should not be submitted to the REPL.

Related to this issue, it would be convenient to be able to tell whether part of a toplevel code block is an error message:

See https://ocaml.org/docs/labels#using-foo-in-a-function-call

As you can see, the error messages is highlighted as if it was regular code, which is confusing for the reader.

[cuihtlauac]

I wonder if there may be even more, we also have:

• Command lines, which can differ by OS and shell
• Problem statements & solution (Here I'd like to write the solution and add an attribute @@problem_solution which would replace it by raise Not_yet_implemented (* Replace with your code *)
• Other formatted text such as JSON, Yaml, HTML or others