CatalaLang/catala
1
1
Fork 0
mirror of https://github.com/CatalaLang/catala.git synced 2024-11-08 07:51:43 +03:00
Code Issues Projects Releases Wiki Activity

Manpage improvements

Browse Source 
- add Vincent as author
- print the full man-page for subcommands (including authors, bugreports, etc.)
- separate debugging commands in a separate section (e.g. the *calc commands)
This commit is contained in:
Louis Gesbert 2024-08-26 15:48:43 +02:00
parent 7819a0a855
commit 9450e3a3f7
3 changed files with 77 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
compiler/catala_utils/cli.ml
View File

@ -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

7
compiler/catala_utils/cli.mli
View File

@ -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) *)

33
compiler/driver.ml
View File

@ -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.")