diff --git a/compiler/catala_utils/cli.ml b/compiler/catala_utils/cli.ml index 62bb24c4..ebb76265 100644 --- a/compiler/catala_utils/cli.ml +++ b/compiler/catala_utils/cli.ml @@ -67,6 +67,9 @@ let exec_dir = (** CLI flags and options *) +let s_plugins = "INSTALLED PLUGINS" +let s_debug = "DEBUGGING COMMANDS" + module Flags = struct open Cmdliner open Arg @@ -425,7 +428,38 @@ end (* Retrieve current version from dune *) let version = Version.v -let s_plugins = "INSTALLED PLUGINS" + +let man_header = + [ + `S Manpage.s_description; + `P + "Catala is a domain-specific language for deriving \ + faithful-by-construction algorithms from legislative texts."; + ] + +let man_footer = + [ + `S Manpage.s_common_options; + `S Manpage.s_authors; + `P "The authors are listed by alphabetical order:"; + `P "Vincent Botbol <$(i,vincent.botbol@inria.fr)>"; + `Noblank; + `P "Nicolas Chataing <$(i,nicolas.chataing@ens.fr)>"; + `Noblank; + `P "Alain Delaët-Tixeuil <$(i,alain.delaet--tixeuil@inria.fr)>"; + `Noblank; + `P "Aymeric Fromherz <$(i,aymeric.fromherz@inria.fr)>"; + `Noblank; + `P "Louis Gesbert <$(i,louis.gesbert@ocamlpro.com)>"; + `Noblank; + `P "Denis Merigoux <$(i,denis.merigoux@inria.fr)>"; + `Noblank; + `P "Emile Rolley <$(i,erolley@tutamail.com)>"; + `S Manpage.s_bugs; + `P "Please file bug reports at https://github.com/CatalaLang/catala/issues"; + ] + +let man_base = man_header @ man_footer let info = let doc = @@ -433,38 +467,24 @@ let info = computation rules." in let man = - [ - `S Manpage.s_synopsis; - `P "$(mname) [$(i,COMMAND)] $(i,FILE) [$(i,OPTION)]…"; - `P - "Use $(mname) [$(i,COMMAND)] $(b,--hel)p for documentation on a \ - specific command"; - `S Manpage.s_description; - `P - "Catala is a domain-specific language for deriving \ - faithful-by-construction algorithms from legislative texts."; - `S Manpage.s_commands; - `S s_plugins; - `S Manpage.s_authors; - `P "The authors are listed by alphabetical order:"; - `P "Nicolas Chataing <$(i,nicolas.chataing@ens.fr)>"; - `Noblank; - `P "Alain Delaët-Tixeuil <$(i,alain.delaet--tixeuil@inria.fr)>"; - `Noblank; - `P "Aymeric Fromherz <$(i,aymeric.fromherz@inria.fr)>"; - `Noblank; - `P "Louis Gesbert <$(i,louis.gesbert@ocamlpro.com)>"; - `Noblank; - `P "Denis Merigoux <$(i,denis.merigoux@inria.fr)>"; - `Noblank; - `P "Emile Rolley <$(i,erolley@tutamail.com)>"; - `S Manpage.s_examples; - `Pre "catala Interpret -s Foo file.catala_en"; - `Pre "catala Ocaml -o target/file.ml file.catala_en"; - `S Manpage.s_bugs; - `P - "Please file bug reports at https://github.com/CatalaLang/catala/issues"; - ] + man_header + @ [ + `S Manpage.s_synopsis; + `P "$(mname) [$(i,COMMAND)] $(i,FILE) [$(i,OPTION)]…"; + `P + "Use $(mname) [$(i,COMMAND)] $(b,--hel)p for documentation on a \ + specific command"; + `S Manpage.s_commands; + `S s_plugins; + `S s_debug; + `P + "These commands are intended for debugging of the Catala compiler \ + itself, and unlikely to be useful to the end-user"; + `S Manpage.s_examples; + `Pre "catala Interpret -s Foo file.catala_en"; + `Pre "catala Ocaml -o target/file.ml file.catala_en"; + ] + @ man_footer in let exits = Cmd.Exit.defaults @ [Cmd.Exit.info ~doc:"on error." 1] in Cmd.info "catala" ~version ~doc ~exits ~man diff --git a/compiler/catala_utils/cli.mli b/compiler/catala_utils/cli.mli index edbbd3dc..160dcde5 100644 --- a/compiler/catala_utils/cli.mli +++ b/compiler/catala_utils/cli.mli @@ -85,6 +85,13 @@ val info : Cmdliner.Cmd.info val s_plugins : string (** Manpage section name for the installed plugins *) +val s_debug : string +(** Name of the manpage section for debugging commands (use as [~docs] arg to + [Arg.info]) *) + +val man_base : Cmdliner.Manpage.block list +(** Skeleton of the manpage shared by all commands *) + exception Exit_with of int (** Exit with a specific exit code (but less brutally than [Sys.exit] which would bypass all finalisers) *) diff --git a/compiler/driver.ml b/compiler/driver.ml index ceecac9f..3f1a11b3 100644 --- a/compiler/driver.ml +++ b/compiler/driver.ml @@ -449,7 +449,7 @@ module Commands = struct let makefile_cmd = Cmd.v - (Cmd.info "makefile" + (Cmd.info "makefile" ~man:Cli.man_base ~doc: "Generates a Makefile-compatible list of the file dependencies of a \ Catala program.") @@ -475,7 +475,7 @@ module Commands = struct let html_cmd = Cmd.v - (Cmd.info "html" + (Cmd.info "html" ~man:Cli.man_base ~doc: "Weaves an HTML literate programming output of the Catala program.") Term.( @@ -524,7 +524,7 @@ module Commands = struct let latex_cmd = Cmd.v - (Cmd.info "latex" + (Cmd.info "latex" ~man:Cli.man_base ~doc: "Weaves a LaTeX literate programming output of the Catala program.") Term.( @@ -548,7 +548,7 @@ module Commands = struct let exceptions_cmd = Cmd.v - (Cmd.info "exceptions" + (Cmd.info "exceptions" ~man:Cli.man_base ~doc: "Prints the exception tree for the definitions of a particular \ variable, for debugging purposes. Use the $(b,-s) option to select \ @@ -579,7 +579,7 @@ module Commands = struct let scopelang_cmd = Cmd.v - (Cmd.info "scopelang" + (Cmd.info "scopelang" ~man:Cli.man_base ~docs:Cli.s_debug ~doc: "Prints a debugging verbatim of the scope language intermediate \ representation of the Catala program. Use the $(b,-s) option to \ @@ -617,7 +617,7 @@ module Commands = struct let typecheck_cmd = Cmd.v - (Cmd.info "typecheck" + (Cmd.info "typecheck" ~man:Cli.man_base ~doc:"Parses and typechecks a Catala program, without interpreting it.") Term.( const typecheck @@ -658,7 +658,7 @@ module Commands = struct if no_typing then dcalc Expr.untyped else dcalc Expr.typed in Cmd.v - (Cmd.info "dcalc" + (Cmd.info "dcalc" ~man:Cli.man_base ~docs:Cli.s_debug ~doc: "Prints a debugging verbatim of the default calculus intermediate \ representation of the Catala program. Use the $(b,-s) option to \ @@ -693,7 +693,7 @@ module Commands = struct let proof_cmd = Cmd.v - (Cmd.info "proof" + (Cmd.info "proof" ~man:Cli.man_base ~doc: "Generates and proves verification conditions about the \ well-behaved execution of the Catala program.") @@ -777,7 +777,7 @@ module Commands = struct if no_typing then lcalc Expr.untyped else lcalc Expr.typed in Cmd.v - (Cmd.info "lcalc" + (Cmd.info "lcalc" ~man:Cli.man_base ~docs:Cli.s_debug ~doc: "Prints a debugging verbatim of the lambda calculus intermediate \ representation of the Catala program. Use the $(b,-s) option to \ @@ -834,7 +834,7 @@ module Commands = struct expand_ops in Cmd.v - (Cmd.info "interpret" + (Cmd.info "interpret" ~man:Cli.man_base ~doc: "Runs the interpreter on the Catala program, executing the scope \ specified by the $(b,-s) option assuming no additional external \ @@ -879,7 +879,7 @@ module Commands = struct let ocaml_cmd = Cmd.v - (Cmd.info "ocaml" + (Cmd.info "ocaml" ~man:Cli.man_base ~doc:"Generates an OCaml translation of the Catala program.") Term.( const ocaml @@ -927,7 +927,7 @@ module Commands = struct let scalc_cmd = Cmd.v - (Cmd.info "scalc" + (Cmd.info "scalc" ~man:Cli.man_base ~docs:Cli.s_debug ~doc: "Prints a debugging verbatim of the statement calculus intermediate \ representation of the Catala program. Use the $(b,-s) option to \ @@ -972,7 +972,7 @@ module Commands = struct let python_cmd = Cmd.v - (Cmd.info "python" + (Cmd.info "python" ~man:Cli.man_base ~doc:"Generates a Python translation of the Catala program.") Term.( const python @@ -999,7 +999,8 @@ module Commands = struct let c_cmd = Cmd.v - (Cmd.info "c" ~doc:"Generates an C translation of the Catala program.") + (Cmd.info "c" ~man:Cli.man_base + ~doc:"Generates an C translation of the Catala program.") Term.( const c $ Cli.Flags.Global.options @@ -1066,7 +1067,7 @@ module Commands = struct let depends_cmd = Cmd.v - (Cmd.info "depends" + (Cmd.info "depends" ~man:Cli.man_base ~doc: "Lists the dependencies of the given catala files, in linking \ order. This includes recursive dependencies and is useful for \ @@ -1084,7 +1085,7 @@ module Commands = struct let pygmentize_cmd = Cmd.v - (Cmd.info "pygmentize" + (Cmd.info "pygmentize" ~man:Cli.man_base ~doc: "This special command is a wrapper around the $(b,pygmentize) \ command that enables support for colorising Catala code.")