# Manual: decouple verbatim and toplevel styles in code examples #1540

Merged
merged 1 commit into from Dec 21, 2017

## Conversation

Projects
None yet
2 participants
Contributor

### Octachron commented Dec 20, 2017

 This small PR tweaks the latex code emitted by manual/tools/caml_tex2.ml in order to decouple the styles of the verbatim and toplevel mode of the caml_example pseudo-environment. More precisely, it adds two latex macros \camlverbatim and \endcamlverbatim that complements the existing \camlexample and \endcamlexample. These macros are emitted in the verbatim variant of the caml example pseudo-mode and are used to tune separately the styles of the classic (aka toplevel) mode and this new verbatim mode as requested by @gasche in #1209 . Moreover, this PR directly exploit this possibility to remove the # prefix in the verbatim mode, see the small examples here.

Member

### gasche commented Dec 20, 2017

 I trust that the PR is correct, but I find the naming a bit confusing (and the patch as well). It seems that {caml_example}[toplevel] is named "example" and {caml_example}[verbatim] is named "verbatim", but that "Caml-example" is used sometimes to denote both modes (in the CSS hierarchy?) and sometimes only for "example"? On the OCaml side I think that this could be clarified by a type example_mode = Toplevel | Verbatim. On the CSS side, I don't quite understand if caml-example is used only for the toplevel (and has caml-input and caml-output as children) or if verbatim modes gets styled as caml-example > caml-verbatim. On the LaTeX/HeVeA side, the comments are currently a bit confusing.
Member

### gasche commented Dec 20, 2017

 (I think this deserves a Changes entry. We need more work on the manual and documentation, and we should credit the work that is happening.)

### Octachronforce-pushed the Octachron:verbatim-mode branch from 60dfa02 to 9c5664cDec 20, 2017

Contributor Author

### Octachron commented Dec 20, 2017

 Since the gap between the emitted TeX code and the etex source code seemed to be the major source of confusion, I have aligned the TeX code with the source: \begin{camlexample}{mode} … \end{camlexample} is now translated to \camlexample{mode} … \endcamlexample rather than \begin{caml_example}{toplevel} ⇒ \camlexample and \begin{caml_example}{toplevel} ⇒ \camlverbatim as before. Similarly, on the hevea side, the mode is now simply added to the class list of the caml_example div.
Member

### gasche commented Dec 20, 2017

 The new code looks nicer to me, thanks @Octachron. There are no tests for this output in the testsuite, how do you know that the result broke none of the two modes? Did you check manually the two modes in the output of the manual build?
Contributor Author

### Octachron commented Dec 20, 2017

Yes, I checked manually the rendering of the two modes for the Hevea and Latex output in the following examples:

Html Latex
verbatim html verbatim pdf verbatim
toplevel html toplevel pdf toplevel

But I somehow failed to check the same version of the .sty file before and messed up the TeX conditionnal, this is fixed now.

I don't know if there is an easy way to test the output of these code examples at the graphical level (comparing postscript files maybe?).

Member

### gasche left a comment

 Approved. Feel free to rebase (if you wish) and merge whenever it feels right.
 manual examples:decouple verbatim/toplevel styles 
 12ea58f 

### Octachron merged commit 17cf59c into ocaml:trunk Dec 21, 2017 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 Author

### Octachron commented Dec 21, 2017

 Rebased and merged, thanks for the review.