New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
caml_example pseudo-environment in the language extension chapter #7551
Comments
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 \begin{verbatim} Turning it into caml_example* without any other change gets me the following error: Processing exten.etex 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). While |
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 I would be happy with whatever you are willing to implement :-) |
Comment author: @Octachron Ok, I have an implementation proposal here: #1194 . |
Comment author: @gasche The behavior that we merged uses a new (non-optional) argument, "toplevel" or "verbatim": \begin{caml_example}{toplevel} for toplevel input (with an expected ;; at the end), and \begin{caml_example}{verbatim} when ";;" delimiters are not expected. Either can be combined with the [error] marker to indicate that we expect the test to fail: \begin{caml_example}{verbatim}[error] Thanks! |
Original bug ID: 7551
Reporter: @Octachron
Assigned to: @gasche
Status: resolved (set by @gasche on 2019-02-20T05:14:22Z)
Resolution: fixed
Priority: low
Severity: feature
Fixed in version: 4.08.0+dev/beta1/beta2
Category: documentation
Tags: manual, junior_job
Monitored by: @gasche
Bug description
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: