caml_example pseudo-environment in the language extension chapter #7551
Original bug ID: 7551
Following a recent change in the manual build, it is now possible to use the "caml_example" pseudo-environment in the language extension chapter of the manual.
Compared to the standard verbatim environment, this pseudo-environment has the advantage to check that the written code is valid, protecting it from bitrot; it also offers the possibility of showing the result of the evaluation of toplevel phrase.
Therefore, it might be a good idea to go through the language extension chapter and replace "verbatim" environment with eitheir "caml_example" or "caml_example*" environment whenever appropriate. The "caml_example" environment should be used whenever the result of the written code is illustrative, whereas the "caml_example*" one discards this results. Another useful environment would be the "caml_eval" environment which can be used to setup the right variables and definition for the "caml_example"'s without displaying anything.
Note that sometimes the verbatim environment is used to introduce "ocaml pseudo-code", in these cases, keeping the verbatim environment is probably better.
The text was updated successfully, but these errors were encountered:
Comment author: @gasche
So I just tried to start working on it, but I realize that caml_example always expects to get well-formed ocaml phrases, and in particular it expects ;; at the end of sequences. For example one verbatim use in the document is
Turning it into caml_example* without any other change gets me the following error:
On the other hand, I don't really want to litter the code with ";;", because I think it's good that some part of the manual would show OCaml code as we write it (and not only toplevel-style code).
Comment author: @Octachron
It should be totally possible to tune caml_tex2 to close toplevel phrase at the end of the environment when the current phrase is non-empty. I remember hesitating between this behavior and the current strict behavior when I implemented the current error message. It should be also quite straightforward to add a [toplevel] option to the environment to enable the strict behavior on missing ";;". I am not sure if it is worthwhile however.
Comment author: @gasche
The behavior that we merged uses a new (non-optional) argument, "toplevel" or "verbatim":
for toplevel input (with an expected ;; at the end), and
when ";;" delimiters are not expected. Either can be combined with the [error] marker to indicate that we expect the test to fail: