From 4ceb793ea7cd03a94c823908b9c17668f6bb46a4 Mon Sep 17 00:00:00 2001 From: octachron Date: Thu, 5 Apr 2018 14:57:48 +0200 Subject: [PATCH 1/6] signature option for caml_example --- manual/manual/macros.hva | 6 +++--- manual/styles/caml-sl.sty | 6 +++--- manual/tools/caml_tex2.ml | 27 ++++++++++++++++++--------- 3 files changed, 24 insertions(+), 15 deletions(-) diff --git a/manual/manual/macros.hva b/manual/manual/macros.hva index 18e453463088..9e1761713ce5 100644 --- a/manual/manual/macros.hva +++ b/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"} } diff --git a/manual/styles/caml-sl.sty b/manual/styles/caml-sl.sty index e870a99fca37..6bcfefe8310b 100644 --- a/manual/styles/caml-sl.sty +++ b/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} } diff --git a/manual/tools/caml_tex2.ml b/manual/tools/caml_tex2.ml index 6b9875e47609..5ed4410a6b8e 100644 --- a/manual/tools/caml_tex2.ml +++ b/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 @@ -260,7 +263,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 +278,11 @@ let process_file file = | exception Not_found -> raise (Missing_mode(file, !phrase_stop)) | "{toplevel}" -> Toplevel | "{verbatim}" -> Verbatim + | "{signature}" -> Signature | _ -> assert false in 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 +305,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 +330,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"; From c2a865e1b8a5a29121c43b5e4d9898b03aea6702 Mon Sep 17 00:00:00 2001 From: octachron Date: Fri, 6 Apr 2018 18:24:50 +0200 Subject: [PATCH 2/6] convert ocamldoc code example to caml_example --- manual/manual/cmds/Makefile | 17 ++++++++++++++++- manual/manual/cmds/ocamldoc.etex | 25 ++++++++++++++++--------- manual/tools/transf.mll | 8 ++++---- 3 files changed, 36 insertions(+), 14 deletions(-) diff --git a/manual/manual/cmds/Makefile b/manual/manual/cmds/Makefile index 6437ae2ca35a..e25baf981cf9 100644 --- a/manual/manual/cmds/Makefile +++ b/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= $(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 . diff --git a/manual/manual/cmds/ocamldoc.etex b/manual/manual/cmds/ocamldoc.etex index fd1d1e7a91bc..73a5839ab4d3 100644 --- a/manual/manual/cmds/ocamldoc.etex +++ b/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,11 @@ 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} +\newcommand{\camlat}{\@} +\begin{caml_example*}{signature} (** The first special comment of the file is the comment associated with the whole module.*) @@ -566,7 +573,7 @@ module type my_module_type = end -\end{verbatim} +\end{caml_example*} %%%%%%%%%%%%% \subsubsection{Comments in {\tt .ml} files} @@ -584,7 +591,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 +647,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,7 +658,7 @@ module type my_module_type = val x : int (* ... *) end -\end{verbatim} +\end{caml_example} %%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The Stop special comment} @@ -659,7 +666,7 @@ 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 +690,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. diff --git a/manual/tools/transf.mll b/manual/tools/transf.mll index 7d17b11b4d06..dcb5f3e211e1 100644 --- a/manual/tools/transf.mll +++ b/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); From 37231465c2c27c180c1e81ba6ecb291137480334 Mon Sep 17 00:00:00 2001 From: octachron Date: Sat, 7 Apr 2018 11:01:53 +0200 Subject: [PATCH 3/6] error message when using signature without * --- manual/tools/caml_tex2.ml | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/manual/tools/caml_tex2.ml b/manual/tools/caml_tex2.ml index 5ed4410a6b8e..508db28e4b6a 100644 --- a/manual/tools/caml_tex2.ml +++ b/manual/tools/caml_tex2.ml @@ -244,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 @@ -280,6 +284,10 @@ let process_file file = | "{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 | Signature -> false | Toplevel -> true in @@ -417,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 + "@[ 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 From 5918e4e14927a06a7b4531559729503318cd6123 Mon Sep 17 00:00:00 2001 From: octachron Date: Sat, 7 Apr 2018 11:08:39 +0200 Subject: [PATCH 4/6] Update changes --- Changes | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Changes b/Changes index 7bde5ce0da4c..85a074bb1a07 100644 --- a/Changes +++ b/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) From c0e103d13bd5539fb89b2a2330fdf14142701630 Mon Sep 17 00:00:00 2001 From: octachron Date: Sat, 5 May 2018 16:47:58 +0200 Subject: [PATCH 5/6] set LD_PATH for manual --- manual/manual/cmds/Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/manual/manual/cmds/Makefile b/manual/manual/cmds/Makefile index e25baf981cf9..3ff916ed4e34 100644 --- a/manual/manual/cmds/Makefile +++ b/manual/manual/cmds/Makefile @@ -12,8 +12,8 @@ TRANSF=$(SET_LD_PATH) $(OCAMLRUN) ../../tools/transf TEXQUOTE=../../tools/texquote2 FORMAT=../../tools/format-intf -CAMLLATEX= $(OCAMLRUN) ../../tools/caml-tex2 -caml "TERM=norepeat $(OCAML)" \ --n 80 -v false +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 From 358b22747a0242b1e21b47890058ec099c7b1d3c Mon Sep 17 00:00:00 2001 From: octachron Date: Sat, 5 May 2018 19:22:18 +0200 Subject: [PATCH 6/6] remove unused latex macro --- manual/manual/cmds/ocamldoc.etex | 1 - 1 file changed, 1 deletion(-) diff --git a/manual/manual/cmds/ocamldoc.etex b/manual/manual/cmds/ocamldoc.etex index 73a5839ab4d3..d7346bb4c14b 100644 --- a/manual/manual/cmds/ocamldoc.etex +++ b/manual/manual/cmds/ocamldoc.etex @@ -464,7 +464,6 @@ placement rules for comments in ".mli" files. \begin{caml_eval} class cl = object end \end{caml_eval} -\newcommand{\camlat}{\@} \begin{caml_example*}{signature} (** The first special comment of the file is the comment associated with the whole module.*)