Skip to content
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

Closed
vicuna opened this issue Jun 4, 2017 · 6 comments
Closed

caml_example pseudo-environment in the language extension chapter #7551

vicuna opened this issue Jun 4, 2017 · 6 comments

Comments

@vicuna
Copy link

vicuna commented Jun 4, 2017

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.

@vicuna
Copy link
Author

vicuna commented Jun 7, 2017

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}
module F(X : sig type c = private < x : int; .. > end) =
struct
let get_x (o : X.c) = o#x
end
module G(X : sig type c = private < x : int; y : int; .. > end) =
struct
include F(X)
let get_y (o : X.c) = o#y
end
\end{verbatim}

Turning it into caml_example* without any other change gets me the following error:

Processing exten.etex
Error when evaluating a caml_example environment in exten.etex:
missing ";;" at line 349

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 ocaml breaks on the code above without a closing double-semicolon, ocaml -stdin correctly accepts it (it parses the two phrases, etc.). Would it be possible for the caml_example environment to also correctly behave in this situation? Maybe we could just stealthily add a ";;" at the end? (It looks like the toplevel does not complain on ";; ;;", which suggests that it would work fine for toplevel-style examples as well.)

@vicuna
Copy link
Author

vicuna commented Jun 7, 2017

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.

@vicuna
Copy link
Author

vicuna commented Jun 7, 2017

Comment author: @gasche

I would be happy with whatever you are willing to implement :-)

@vicuna
Copy link
Author

vicuna commented Jun 7, 2017

Comment author: @Octachron

Ok, I have an implementation proposal here: #1194 .

@vicuna
Copy link
Author

vicuna commented Jun 7, 2017

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]
1 + "foo"
\end{caml_example}

Thanks!

@vicuna
Copy link
Author

vicuna commented Feb 20, 2019

Comment author: @gasche

This has been largely fixed by the following PRs (plus tooling support from Octachron):

#1209
#2008

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants