Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0007551OCamldocumentationpublic2017-06-04 13:502017-07-11 21:44
Reporteroctachron 
Assigned To 
PrioritylowSeverityfeatureReproducibilityalways
StatusconfirmedResolutionopen 
PlatformOSOS Version
Product Version 
Target VersionFixed in Version 
Summary0007551: caml_example pseudo-environment in the language extension chapter
DescriptionFollowing 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.
Tagsjunior_job, manual
Attached Files

- Relationships

-  Notes
(0017845)
gasche (developer)
2017-06-07 02:51

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.)
(0017846)
octachron (developer)
2017-06-07 03:07

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.
(0017847)
gasche (developer)
2017-06-07 03:31

I would be happy with whatever you are willing to implement :-)
(0017849)
octachron (developer)
2017-06-07 16:46

Ok, I have an implementation proposal here: https://github.com/ocaml/ocaml/pull/1194 [^] .
(0017850)
gasche (developer)
2017-06-07 21:01

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!

- Issue History
Date Modified Username Field Change
2017-06-04 13:50 octachron New Issue
2017-06-04 13:50 octachron Tag Attached: junior_job
2017-06-04 13:50 octachron Tag Attached: manual
2017-06-07 02:51 gasche Note Added: 0017845
2017-06-07 03:07 octachron Note Added: 0017846
2017-06-07 03:31 gasche Note Added: 0017847
2017-06-07 16:46 octachron Note Added: 0017849
2017-06-07 21:01 gasche Note Added: 0017850
2017-07-11 21:44 octachron Status new => confirmed


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker