manual: signature option for caml_example

Changes

@@ -381,6 +381,9 @@ OCaml 4.07
 - GPR#1647: manual, subsection on record and variant disambiguation
   (Florian Angeletti, review by Alain Frisch and Gabriel Scherer)
 
+- GPR#1702: manual, add a signature mode for code examples
+  (Florian Angeletti, review by Gabriel Scherer)
+
 - GPR#1741: manual, improve typesetting and legibility in HTML output
   (steinuil, review by Gabriel Scherer)
 

manual/manual/cmds/Makefile

@@ -12,9 +12,14 @@ TRANSF=$(SET_LD_PATH) $(OCAMLRUN) ../../tools/transf
 TEXQUOTE=../../tools/texquote2
 FORMAT=../../tools/format-intf
 
-WITH_TRANSF= ocamldoc.tex top.tex intf-c.tex flambda.tex spacetime.tex \
+CAMLLATEX=$(SET_LD_PATH) $(OCAMLRUN) ../../tools/caml-tex2 \
+-caml "TERM=norepeat $(OCAML)" -n 80 -v false
+
+WITH_TRANSF= top.tex intf-c.tex flambda.tex spacetime.tex \
   afl-fuzz.tex lexyacc.tex debugger.tex
 
+WITH_CAMLEXAMPLE = ocamldoc.tex
+
 etex-files: $(FILES)
 
 all: $(FILES)
@@ -38,6 +43,16 @@ $(WITH_TRANSF):%.tex:%.etex
 	&& mv $*.texquote_error.tex $*.tex \
 	|| printf "Failure when generating %s\n" $*.tex
 
+
+$(WITH_CAMLEXAMPLE):%.tex:%.etex
+	@$(CAMLLATEX) -o $*.caml_tex_error.tex $*.etex \
+	&& mv $*.caml_tex_error.tex $*.gen.tex \
+	&& $(TRANSF) < $*.gen.tex > $*.transf_error.tex \
+	&& mv $*.transf_error.tex $*.gen.tex\
+	&& $(TEXQUOTE) < $*.gen.tex  > $*.texquote_error.tex\
+	&& mv $*.texquote_error.tex $*.tex\
+	|| printf "Failure when generating %s\n" $*.tex
+
 warnings-help.etex: ../warnings-help.etex
 	cp ../warnings-help.etex .
 

manual/manual/cmds/ocamldoc.etex

@@ -401,7 +401,10 @@ resulting in cross-reference errors:
 \item Values defined in tuple, as in "let (x,y,z) = (1,2,3)"
 are not kept by OCamldoc.
 \item Avoid the following construction:
-\begin{verbatim}
+\begin{caml_eval}
+module Foo = struct module Bar = struct let x = 1 end end;;
+\end{caml_eval}
+\begin{caml_example*}{verbatim}
 open Foo (* which has a module Bar with a value x *)
 module Foo =
   struct
@@ -411,7 +414,7 @@ module Foo =
       end
   end
   let dummy = Bar.x
-\end{verbatim}
+\end{caml_example*}
 In this case, OCamldoc will associate "Bar.x" to the "x" of module
 "Foo" defined just above, instead of to the "Bar.x" defined in the
 opened module "Foo".
@@ -458,7 +461,10 @@ character separating the two constructors.
 The following sample interface file "foo.mli" illustrates the
 placement rules for comments in ".mli" files.
 
-\begin{verbatim}
+\begin{caml_eval}
+class cl = object end
+\end{caml_eval}
+\begin{caml_example*}{signature}
 (** The first special comment of the file is the comment associated
     with the whole module.*)
 
@@ -566,7 +572,7 @@ module type my_module_type =
 
   end
 
-\end{verbatim}
+\end{caml_example*}
 
 %%%%%%%%%%%%%
 \subsubsection{Comments in {\tt .ml} files}
@@ -584,7 +590,7 @@ character separating the two constructors.
 The following example of file "toto.ml" shows where to place comments
 in a ".ml" file.
 
-\begin{verbatim}
+\begin{caml_example*}{verbatim}
 (** The first special comment of the file is the comment associated
     to the whole module. *)
 
@@ -640,7 +646,7 @@ class type my_class_type =
 module Foo =
   struct
     (** The comment for x *)
-    val x : int
+    let x = 0
     (** A special comment in the class, but not associated to any element. *)
   end
 
@@ -651,15 +657,15 @@ module type my_module_type =
     val x : int
     (* ... *)
   end
-\end{verbatim}
+\end{caml_example}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%
 \subsection{The Stop special comment}
 The special comment "(**/**)" tells OCamldoc to discard
 elements placed after this comment, up to the end of the current
 class, class type,  module or module type, or up to the next stop comment.
 For instance:
-\begin{verbatim}
+\begin{caml_example*}{signature}
 class type foo =
   object
     (** comment for method m *)
@@ -683,7 +689,7 @@ val bar : string
 (** The type t appears since in the documentation since the previous stop comment
 toggled off the "no documentation mode". *)
 type t = string
-\end{verbatim}
+\end{caml_example*}
 
 The {\bf\tt -no-stop} option to "ocamldoc" causes the Stop special
 comments to be ignored.

manual/manual/macros.hva

@@ -82,9 +82,9 @@
 
 % Caml-example environment
 \newcommand{\camlexample}[1]{
-  \ifthenelse{\equal{#1}{verbatim}}
-  {\renewcommand{\examplespace}{}}
-  {\renewcommand{\examplespace}{\ }}
+  \ifthenelse{\equal{#1}{toplevel}}
+    {\renewcommand{\examplespace}{\ }}
+    {\renewcommand{\examplespace}{}}
   \fi
   \@open{div}{class="caml-example #1"}
 }

manual/styles/caml-sl.sty

@@ -43,10 +43,10 @@
 
 % Caml-example related command
 \def\camlexample#1{
-  \ifnum\pdfstrcmp{#1}{verbatim}=0
-  \renewcommand{\hash}{}
+  \ifnum\pdfstrcmp{#1}{toplevel}=0
+    \renewcommand{\hash}{\#}
   \else
-  \renewcommand{\hash}{\#}
+    \renewcommand{\hash}{}
   \fi
   \begin{flushleft}
 }

manual/tools/caml_tex2.ml

@@ -25,10 +25,11 @@ let code_env ?(newline=true) env out s =
     (fun ppf env -> start false ppf env []) env s (stop newline) env
 
 let main = "example"
-type example_mode = Toplevel | Verbatim
+type example_mode = Toplevel | Verbatim | Signature
 let string_of_mode =  function
   | Toplevel -> "toplevel"
   | Verbatim -> "verbatim"
+  | Signature -> "signature"
 
 let input_env = "input"
 let ok_output ="output"
@@ -107,7 +108,7 @@ module Output = struct
   exception Unexpected_status of unexpected_report
 
   let print_source ppf {file; lines = (start, stop); phrase; output} =
-    Printf.fprintf ppf "%s, lines %d to %d:\n\"\n%s\n%s\n\"."
+    Printf.fprintf ppf "%s, lines %d to %d:\n\"\n%s\n\"\n\"\n%s\n\"."
       file start stop phrase output
 
   let print_unexpected {source; expected; got} =
@@ -211,7 +212,9 @@ let () =
 
 let read_output () =
   let input = ref (input_line caml_input) in
-  input := replace_first ~!"^# *" "" !input;
+  input := replace_first ~!{|^#\( *\*\)* *|} "" !input;
+  (* the inner ( *\* )* group is here to clean the starting "*"
+     introduced for multiline comments *)
   let underline =
     if string_match ~!"Characters *\\([0-9]+\\)-\\([0-9]+\\):$" !input 0
     then
@@ -241,6 +244,10 @@ exception Missing_double_semicolon of string * int
 
 exception Missing_mode of string * int
 
+type incompatibility =
+  | Signature_with_visible_answer of string * int
+exception Incompatible_options of incompatibility
+
 let process_file file =
   prerr_endline ("Processing " ^ file);
   let ic = try open_in file with _ -> failwith "Cannot read input file" in
@@ -260,7 +267,7 @@ let process_file file =
   let re_spaces = "[ \t]*" in
   let re_start = ~!(
       {|\\begin{caml_example\(\*?\)}|} ^ re_spaces
-      ^ {|\({toplevel}\|{verbatim}\)?|} ^ re_spaces
+      ^ {|\({toplevel}\|{verbatim}\|{signature}\)?|} ^ re_spaces
       ^ {|\(\[\(.*\)\]\)?|} ^ re_spaces
       ^ "$"
     ) in
@@ -275,10 +282,15 @@ let process_file file =
         | exception Not_found -> raise (Missing_mode(file, !phrase_stop))
         | "{toplevel}" -> Toplevel
         | "{verbatim}" -> Verbatim
+        | "{signature}" -> Signature
         | _ -> assert false in
+      if mode = Signature && not omit_answer then raise
+          (Incompatible_options(
+              Signature_with_visible_answer(file,!phrase_stop))
+          );
       let explicit_stop = match mode with
-        | Verbatim -> false
-        | Toplevel -> true  in
+        | Verbatim | Signature -> false
+        | Toplevel -> true in
       let global_expected = try Output.expected @@ matched_group 4 !input
         with Not_found -> Output.Ok in
       start true oc main [string_of_mode mode];
@@ -301,8 +313,11 @@ let process_file file =
               end
             else false in
           if Buffer.length phrase > 0 then Buffer.add_char phrase '\n';
-          let stop = implicit_stop
-                     || string_match ~!"\\(.*\\)[ \t]*;;[ \t]*$" input 0 in
+          let stop =
+            implicit_stop ||
+            ( not (mode = Signature)
+              && string_match ~!"\\(.*\\)[ \t]*;;[ \t]*$" input 0 )
+          in
           if not stop then (
             Buffer.add_string phrase input; read ()
           )
@@ -323,7 +338,9 @@ let process_file file =
       in
       try while true do
         let implicit_stop, phrase, expected = read_phrase () in
-        fprintf caml_output "%s%s" phrase
+        if mode = Signature then fprintf caml_output "module type Wrap = sig\n";
+        fprintf caml_output "%s%s%s" phrase
+        (if mode = Signature then "\nend" else "")
         (if implicit_stop then ";;\n" else "\n");
         flush caml_output;
         output_string caml_output "\"end_of_input\";;\n";
@@ -408,7 +425,16 @@ let process_file file =
         close_in ic; close_out oc;
         exit 1
       )
-
+  | Incompatible_options Signature_with_visible_answer (file, line_number) ->
+      ( Format.eprintf
+          "@[<hov 2>  Error when parsing a caml_example environment in@ \
+           %s, line %d:@,\
+           the signature mode is only compatible with \"caml_example*\"@ \
+           Hint: did you forget to add \"*\"?@]@."
+          file (line_number-2);
+        close_in ic; close_out oc;
+        exit 1
+      )
 
 let _ =
   if !outfile <> "-" && !outfile <> "" then begin

manual/tools/transf.mll

@@ -14,8 +14,8 @@ rule main = parse
     "\\begin{syntax}" {
       print_string "\\begin{syntax}";
       syntax lexbuf }
-  | "\\begin{verbatim}" {
-      print_string "\\begin{verbatim}";
+  | "\\begin{verbatim}" | "\\camlexample" as s {
+      print_string s;
       verbatim lexbuf }
   | "\\@" {
       print_string "@";
@@ -99,8 +99,8 @@ and indoublequote = parse
       indoublequote lexbuf }
 
 and verbatim = parse
-    "\n\\end{verbatim}" {
-      print_string "\n\\end{verbatim}";
+    "\n\\end{verbatim}"|"\\endcamlexample" as s {
+      print_string s;
       main lexbuf }
   | _ {
       print_char (lexeme_char lexbuf 0);