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

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
@Octachron
Copy link
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.

@Octachron Octachron requested a review from gasche Dec 20, 2017

@gasche

This comment has been minimized.

Copy link
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.

@gasche

This comment has been minimized.

Copy link
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.)

@Octachron Octachron force-pushed the Octachron:verbatim-mode branch from 60dfa02 to 9c5664c Dec 20, 2017

@Octachron

This comment has been minimized.

Copy link
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.

@gasche

This comment has been minimized.

Copy link
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?

@Octachron

This comment has been minimized.

Copy link
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?).

@gasche

gasche approved these changes Dec 20, 2017

Copy link
Member

gasche left a comment

Approved. Feel free to rebase (if you wish) and merge whenever it feels right.

@Octachron Octachron force-pushed the Octachron:verbatim-mode branch from fd9030a to 12ea58f Dec 21, 2017

@Octachron Octachron merged commit 17cf59c into ocaml:trunk Dec 21, 2017

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 Author

Octachron commented Dec 21, 2017

Rebased and merged, thanks for the review.

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.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.