Join GitHub today
GitHub is home to over 50 million developers working together to host and review code, manage projects, and build software together.Sign up
GitHub is where the world builds software
Millions of developers and companies build, ship, and maintain their software on GitHub — the largest and most advanced development platform in the world.
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.
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: