Cmdliner.Term.Syntax (#173). Thanks to Benoit Montagu for suggesting, Gabriel Scherer for reminding us of language punning obscurities and Sebastien Mondet for strengthening the case to add them.$(iname) in the default introduction of the ENVIRONMENT section. Follow up to #168.Cmd.eval_value' a variation on Cmd.eval_value.$(iname) substitutes the command invocation (from program name to subcommand) in bold (#168). This variable is now used in the default introduction of the EXIT STATUS section. Thanks to Ali Caglayan for suggesting.PAGER=less is set (#167).`Noblank. Thanks to Michael Richards and Reynir Björnsson for the report (#176).Term.ret (#135).Term.ret (`Help (fmt, None) (#135).?deprecated argument of Cmd.info, Cmd.Env.info and Arg.info.Manpage.s_none a special section name to use whenever you want something not to be listed in a command's manpage.Arg.conv' like Arg.conv but with a parser signature that returns untagged string errors.Term.{term,cli_parse}_result' functions.command -v rather than type to find commands..mli to multiple .mld pages.Arg.doc_alts and Arg.doc_alts_enum, change the default rendering to match the manpage convention which is to render these tokens in bold. If you want to recover the previous rendering or were using these functions outside man page rendering use an explicit ~quoted:true (the optional argument is available on earlier versions).Term.exit and Term.exit_status_of_result now require a unit result. This avoids various errors to go undetected. Thanks to Thomas Leonard for the patch (#124).Fix absent and default option values (?none string argument of Arg.some) rendering in manpages:
If you were relying on the third point via ?none of Arg.some, use the new ?absent optional argument of Arg.info instead. Besides a new Arg.some' function is added to specify a value for ?none instead of a string. Thanks to David Allsopp for the patch (#111).
… (U+2026) instead of ... for ellipsis. See also UTF-8 manpage support below.Cmd module and deprecation of the Term evaluation interfaceThis version of cmdliner deprecates the Term.eval* evaluation functions and Term.info information values in favor of the new Cmdliner.Cmd module.
The Cmd module generalizes the existing sub command support to allow arbitrarily nested sub commands each with its own man page and command line syntax represented by a Term.t value.
The mapping between the old interface and the new one should be rather straightforward. In particular Term.info and Cmd.info have exactly the same semantics and fields and a command value simply pairs a command information with a term.
However in this transition the following things are changed or added:
All default values of Cmd.info match those of Term.info except for:
?exits argument which defaults to Cmd.Exit.defaults rather than the empty list.?man_xrefs which defaults to the list [`Main] rather than the empty list (this means that by default sub commands at any level automatically cross-reference the main command).?sdocs argument which defaults to Manpage.s_common_options rather than Manpage.s_options.Cmd.Exit.some_error code is added to Cmd.Exit.defaults (which in turn is the default for Cmd.info see above). This is an error code clients can use when they don't want to bother about having precise exit codes. It is high so that low, meaningful, codes can later be added without breaking a tool's compatibility. In particular the convenience evaluation functions Cmd.eval_result* use this code when they evaluate to an error.?term_err defaulting to 1 in the various Term.exit* function, note that the new Cmd.eval* function use Exit.cli_error as a default. You may want to explicitly specify 1 instead if you use Term.ret with the `Error case or Term.term_result.Finally be aware that if you replace, in an existing tool, an encoding of sub commands as positional arguments you will effectively break the command line compatibility of your tool since options can no longer be specified before the sub commands, i.e. your tool synopsis moves from:
tool cmd [OPTION]… SUBCMD [ARG]…to
tool cmd SUBCMD [OPTION]… [ARG]…Thanks to Rudi Grinberg for prototyping the feature in #123.
It is now possible to write UTF-8 encoded text in your doc strings and man pages.
The man page renderer used on --help defaults to mandoc if available, then uses groff and then defaults to nroff. Starting with mandoc catches macOS whose groff as of 11.6 still doesn't support UTF-8 input and struggles to render some Unicode characters.
The invocations were also tweaked to remove the -P-c option which entails that the default pager less is now invoked with the -R option.
If you install UTF-8 encoded man pages output via --help=groff, in man directories bear in mind that these pages will look garbled on stock macOS (at least until 11.6). One way to work around is to instruct your users to change the NROFF definition in /private/etc/man.conf from:
NROFF /usr/bin/groff -Wall -mtty-char -Tascii -mandoc -cto:
NROFF /usr/bin/mandoc -Tutf8 -cThanks to Antonin Décimo for his knowledge and helping with these mangnificent intricacies (#27).
Error (_, e) term evaluation results are formatted. Instead of treating e as text, treat it as formatted lines.Pervasives deprecation.Makefile bootstrap build reproducible. Thanks to Thomas Leonard for the patch.Term.with_used_args. Thanks to Jeremie Dimino for the patch.Makefile bootstrap build in opam file.Makefile bootstrap build.Makefile from the distribution.Makefile to build and install cmdliner without topkg and opam .install files. Helps bootstraping opam in OS package managers. Thanks to Hendrik Tews for the patches.IMPORTANT The Arg.converter type is deprecated in favor of the Arg.conv type. For this release both types are equal but the next major release will drop the former and make the latter abstract. All users are kindly requested to migrate to use the new type and only via the new Arg.[p]conv and Arg.conv_{parser,printer} functions.
Term.exit[_status] and Term.exit_status_of[_status]_result. improves composition with Pervasives.exit.Term.term_result and Term.cli_parse_result improves composition with terms evaluating to result types.Arg.parser_of_kind_of_string.Arg.pos_left (see #76 for details).Term.man_format in favor of Arg.man_format.--cmdliner option for library use. This is unused for now but will be in the future.The following changes affect the end-user behaviour of all binaries using cmdliner.
--help[=FMT] option. FMT no longer defaults to pager if unspecified. It defaults to the new value auto which prints the help as pager or plain whenever the TERM environment variable is dumb or undefined (#43). At the API level this changes the signature of the type Term.ret and values Term.ret, Term.man_format (deprecated) and Manpage.print to add the new `Auto case to manual formats. These are now represented by the Manpage.format type rather than inlined polyvars.?envs optional argument to Term.info. Documents environment variables that influence a term's evaluation and automatically integrate them in the manual.?exits optional argument to Term.info. Documents exit statuses of the program. Use Term.default_exits if you are using the new Term.exit functions.?man_xrefs optional argument to Term.info. Documents references to other manpages. Automatically formats a SEE ALSO section in the manual.Manpage.escape to escape a string from the documentation markup language.Manpage.s_* constants for standard man page section names. `Blocks case to Manpage.blocks to allow block splicing (#69). This avoids having to concatenate block lists at the toplevel of your program.Arg.env_var, change default environment variable section to the standard ENVIRONMENT manual section rather than ENVIRONMENT VARIABLES. If you previously manually positioned that section in your man page you will have to change the name. See also next point.NAME section can now also be overridden manually.an macros directly in the man page via .mso this makes man pages self-describing and avoids having to call groff with the -man option.This release tries to bring sanity to the doc language. This may break the rendering of some of your man pages. Thanks to Gabriel Scherer, Ivan Gotovchits and Nicolás Ojeda Bär for the feedback.
$(var) that are mentioned in the docs ($(docv), $(opt), etc.) and the markup directives $({i,b},text). Any other unknown $(var) will generate errors on standard error during documentation generation.$({i,b},text) treat text as is, modulo escapes; see next point.$, (, ) and \ can respectively be escaped by \$, \(, \) and \\. Escaping $ and \ is mandatory everywhere. Escaping ) is mandatory only in markup directives. Escaping ( is only here for your symmetric pleasure. Any other sequence of character starting with a \ is an illegal sequence.$(mname) and $(tname) are now marked up with bold when substituted. If you used to write $(b,$(tname)) this will generate an error on standard output, since $ is not escaped in the markup directive. Simply replace these by $(tname).Manpage.block type which can break existing programs. Thanks to Guillaume Bury for suggesting and help.env optional argument to the Arg.info function which can break existing programs.$(opt) can be used to refer to the name of the option being documented and $(env) for the name of the option's the environment variable.Term.pure in favor of Term.const.$(undef) would be turned into undef.Not_found exceptions into Invalid_arg. These can be triggered by client programming errors (e.g. an unclosed variable in a documentation string).ocamlfind. The package no longer depends on ocamlfind. Thanks to Louis Gesbert for the patch.tar -xvzf archive.tgz or tar -xvzfarchive.tgz. Previously this resulted in an error, all the short flags had to be specified separately. Backward compatible in the sense that only more command lines are parsed. Thanks to Hugo Heuzard for the patch.Arg.doc_{quote,alts,alts_enum}, documentation string helpers.Term.eval_peek_opts function for advanced usage scenarios.Arg.enum now raises Invalid_argument if the enumeration is empty.Oo (was used to get program uuid).$MANPAGER as well. Thanks to Raphaël Proust for the patch.SYNOPSIS sections.Arg.pos_right.$(tname) and $(mname) can be used in a term's man page to respectively refer to the term's name and the main term name.Manpage.print.Term.man_format, to facilitate the definition of help commands.Incompatible API changes:
Term.eval and Term.eval_choice changed to make it more regular: the given term and its info must be tupled together even for the main term and the tuple order was swapped to make it consistent with the one used for arguments.