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

Change verbatim to caml_example in documentation #2105

Merged
merged 4 commits into from Oct 15, 2018

Conversation

Projects
None yet
2 participants
@Peaupote
Copy link
Contributor

commented Oct 13, 2018

Hi !

I added a paragraph in the manual's readme about the {signature} option of the caml_example environment.

I also changed some verbatim environment to caml_example in chapters 7.7 and 7.11 where there was some code left untested.

Thanks

Add paragraph in manual's readme about signature option in caml_examp…
…le env. Change verbatim env to caml_example.
@Octachron

This comment has been minimized.

Copy link
Contributor

commented Oct 13, 2018

Mentioning the signature mode in the README.md is a nice idea. I would mention this mode directly in the introductive enumeration, going from

The {verbatim} or {toplevel} argument of the environment corresponds
to the the mode of the example, two modes are available toplevel and
verbatim.

to

The {verbatim} or {toplevel} argument of the environment corresponds
to the the mode of the example, three modes are available toplevel, verbatim and signature.

you must use the `{signature}` argument to the `caml_example` environment.
```latex
\begin{caml_example*}{signature}
module A : sig

This comment has been minimized.

Copy link
@Octachron

Octachron Oct 13, 2018

Contributor

I would start the example with a value

val none : 'a option

since the keyword val is only used in signature and thus make it clear that this is signature example on the first word of the example, whereas using a module requires to read three tokens.

\end{verbatim}
\begin{caml_example*}{verbatim}
module S = struct type t = int let x = 2 end
\end{caml_example}
the module expression

This comment has been minimized.

Copy link
@Octachron

Octachron Oct 13, 2018

Contributor

There is a small mismatch between the text and the code, module B = ... is no longer a module expression but a module definition.

This comment has been minimized.

Copy link
@Peaupote

Peaupote Oct 13, 2018

Author Contributor

Thank you for responding so quickly !

I added the module B = ... because the module expression is not an ocaml declaration itself, so caml_example wouldn't accept it.
Should I leave it as it was or should I reformulate the text to make it match with the code ?

This comment has been minimized.

Copy link
@Octachron

Octachron Oct 13, 2018

Contributor

Simply reformulate the text seems fine: this is an example for include and using a module definition rather than a structure is still one of the most frequent use case.

\end{verbatim}
\begin{caml_example*}{verbatim}
module B = struct include S let y = (x + 1 : t) end
\end{caml_example}
is equivalent to the module expression

This comment has been minimized.

Copy link
@Octachron

Octachron Oct 13, 2018

Contributor

Same as above.

\begin{caml_example*}{signature}
val none : 'a option
\end{caml_example*}
```

This comment has been minimized.

Copy link
@Octachron

Octachron Oct 14, 2018

Contributor

One last change: I think it is better to place this example after the description of the signature mode,

If you want to declare a signature instead of ocaml code,
you must use the {signature} argument to the caml_example environment:

\begin{caml_example*}{signature} 
...
\end{caml_example*}
\begin{caml_example*}{verbatim}
module B = struct include S let y = (x + 1 : t) end
\end{caml_example}
is equivalent to do

This comment has been minimized.

Copy link
@Octachron

Octachron Oct 14, 2018

Contributor

I missed this typo: it should be is equivalent to or is equivalent to defining it as .

@Octachron
Copy link
Contributor

left a comment

It looks good to me.

@Octachron Octachron merged commit 74e3b9a into ocaml:trunk Oct 15, 2018

2 checks passed

continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@Octachron

This comment has been minimized.

Copy link
Contributor

commented Oct 15, 2018

Merged, thanks for the PR!

damiendoligez added a commit to damiendoligez/ocaml that referenced this pull request Nov 5, 2018

Change verbatim to caml_example in documentation (ocaml#2105)
* Add paragraph in manual's readme about signature option in caml_example env. Change verbatim env to caml_example.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.