# Change verbatim to caml_example in documentation #2105

Merged
merged 4 commits into from Oct 15, 2018

## Conversation

Projects
None yet
2 participants
Contributor

### Peaupote 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.
 854ddf3 
Contributor

### Octachron 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.

### Octachron reviewed Oct 13, 2018

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

#### 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.

### Octachron reviewed Oct 13, 2018

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

#### 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.

#### 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 ?

#### 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.

### Octachron reviewed Oct 13, 2018

 \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

#### Octachron Oct 13, 2018

Contributor

Same as above.

 fix mismatch and rewrite caml_example section in the manual README 
 27e6206 

### Octachron reviewed Oct 14, 2018

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

#### 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*}
 move signature example after its description 
 51c6264 

### Octachron reviewed Oct 14, 2018

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

#### Octachron Oct 14, 2018

Contributor

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

 fix typo 
 beef08f 

Contributor

### Octachron left a comment

 It looks good to me.

### Octachron merged commit 74e3b9a into ocaml:trunk Oct 15, 2018 2 checks passed

#### 2 checks passed

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

### Octachron 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.
 aa4306c