manual examples:decouple verbatim/toplevel styles

Changes

@@ -109,6 +109,9 @@ Working version
 - PR#7647, GPR#1384: emphasize ocaml.org website and forum in README
   (Yawar Amin, review by Gabriel Scherer)
 
+- GPR#1540: manual, decouple verbatim and toplevel style in code examples
+  (Florian Angeletti, review by Gabriel Scherer)
+
 ### Compiler distribution build system
 
 - MPR#7679: make sure .a files are erased before calling ar rc, otherwise

manual/manual/macros.hva

@@ -6,31 +6,43 @@
 \newstyle{a:visited}{color:\visited@color;text-decoration:underline;}
 \newstyle{a:hover}{color:black;text-decoration:none;background-color:\hover@color}
 
+%Styles for caml-example and friends
 \newstyle{div.caml-output}{color:maroon;}
-\newstyle{div.caml-input::before}{content:"\#"; color:black;}
-\newstyle{div.caml-input}{color:\#006000;}
 \newstyle{div.caml-example pre}{margin:2ex 0px;}
-
+% Styles for toplevel mode only
+\newstyle{div.caml-example.toplevel div.caml-input::before}
+         {content:"\#"; color:black;}
+\newstyle{div.caml-example.toplevel div.caml-input}{color:\#006000;}
 %%%
 \newcommand{\input@color}{\htmlcolor{006000}}
 \newcommand{\output@color}{\maroon}
 \newcommand{\machine}{\tt}
 \newenvironment{machineenv}{\begin{alltt}}{\end{alltt}}
 \newcommand{\firstline}{\ }
-\newcommand{\nextline}{\ \ }
+\newcommand{\examplespace}{\ }
+\newcommand{\nextline}{\examplespace\ }
 \newcommand{\@zyva}{\firstline\renewcommand{\?}{\nextline}}
+\let\?=\@zyva
 \newenvironment{camlunder}{\@style{U}}{}
 \newcommand{\caml}{\begin{alltt}\renewcommand{\;}{}\renewcommand{\\}{\char92}\def\<{\begin{camlunder}}\def\>{\end{camlunder}}\activebracefalse}
-\let\?=\@zyva
 \newcommand{\endcaml}{\activebracetrue\end{alltt}
 }
 \renewcommand{\:}{\renewcommand{\?}{\@zyva}}
 \newcommand{\var}[1]{\textit{#1}}
 
 % Caml-example environment
-\newcommand{\camlexample}{\@open{div}{class="caml-example"}
+\newcommand{\camlexample}[1]{
+  \ifthenelse{\equal{#1}{verbatim}}
+  {\renewcommand{\examplespace}{}}
+  {\renewcommand{\examplespace}{\ }}
+  \fi
+  \@open{div}{class="caml-example #1"}
 }
-\newcommand{\endcamlexample}{\@close{div}}
+\newcommand{\endcamlexample}{
+  \@close{div}
+  \renewcommand{\examplespace}{\ }
+}
+
 \newcommand{\camlinput}{\@open{div}{class="caml-input"}}
 \newcommand{\endcamlinput}{\@close{div}}
 \newcommand{\camloutput}{\@open{div}{class="caml-output ok"}}

manual/styles/caml-sl.sty

@@ -1,9 +1,9 @@
 % CAML style option, for use with the caml-latex filter.
 
 \typeout{Document Style option `caml-sl' <7 Apr 92>.}
-
+\newcommand{\hash}{\#}
 {\catcode`\^^M=\active %
- \gdef\@camlinputline#1^^M{\normalsize\tt\# #1\par} %
+ \gdef\@camlinputline#1^^M{\normalsize\tt\hash{} #1\par} %
  \gdef\@camloutputline#1^^M{\small\ttfamily\slshape#1\par} } %
 \def\@camlblankline{\medskip}
 \chardef\@camlbackslash="5C
@@ -42,8 +42,15 @@
 }
 
 % Caml-example related command
-\def\camlexample{\begin{flushleft}}
-\def\endcamlexample{\end{flushleft}}
+\def\camlexample#1{
+  \ifnum\pdfstrcmp{#1}{verbatim}=0
+  \renewcommand{\hash}{}
+  \else
+  \renewcommand{\hash}{\#}
+  \fi
+  \begin{flushleft}
+}
+\def\endcamlexample{\end{flushleft}\renewcommand{\hash}{\#}}
 \def\camlinput{}
 \def\endcamlinput{}
 \def\camloutput{}

manual/tools/caml_tex2.ml

@@ -11,8 +11,9 @@ let camlout = {|\\:\1|}
 let camlbunderline = "\\<"
 let camleunderline = "\\>"
 
-let start newline out s =
+let start newline out s args =
   Printf.fprintf out "%s%s" camlbegin s;
+  List.iter (Printf.fprintf out "{%s}") args;
   if newline then Printf.fprintf out "\n"
 
 let stop newline out s =
@@ -21,9 +22,14 @@ let stop newline out s =
 
 let code_env ?(newline=true) env out s =
   Printf.fprintf out "%a%s\n%a"
-    (start false) env s (stop newline) env
+    (fun ppf env -> start false ppf env []) env s (stop newline) env
 
 let main = "example"
+type example_mode = Toplevel | Verbatim
+let string_of_mode =  function
+  | Toplevel -> "toplevel"
+  | Verbatim -> "verbatim"
+
 let input_env = "input"
 let ok_output ="output"
 let error ="error"
@@ -264,15 +270,18 @@ let process_file file =
     if string_match re_start !input 0
     then begin
       let omit_answer = matched_group 1 !input = "*" in
-      let explicit_stop =
+      let mode =
         match matched_group 2 !input with
         | exception Not_found -> raise (Missing_mode(file, !phrase_stop))
-        | "{toplevel}" -> true
-        | "{verbatim}" -> false
+        | "{toplevel}" -> Toplevel
+        | "{verbatim}" -> Verbatim
         | _ -> assert false in
+      let explicit_stop = match mode with
+        | Verbatim -> false
+        | Toplevel -> true  in
       let global_expected = try Output.expected @@ matched_group 4 !input
         with Not_found -> Output.Ok in
-      start true oc main;
+      start true oc main [string_of_mode mode];
       let first = ref true in
       let read_phrase () =
         let phrase = Buffer.create 256 in
@@ -348,7 +357,7 @@ let process_file file =
         let output = escape_specials output in
         let phrase = global_replace ~!{|^\(.\)|} camlin phrase
         and output = global_replace ~!{|^\(.\)|} camlout output in
-        start false oc phrase_env;
+        start false oc phrase_env [];
         code_env ~newline:omit_answer input_env oc phrase;
         if not omit_answer then
           code_env ~newline:false (Output.env status) oc output;