Arg.enum values to be specified by a prefix if the prefix is unambiguous. See #200 for the rationale. To quickly salvage scripts that may be relying on the old behaviour, it can be restored by setting the environment variable CMDLINER_LEGACY_PREFIXES=true. However the scripts should be fixed: this escape hatch will be removed in the future.LESS environment variable (otherwise the default LESS=FRX is left unchanged). Note however that you likely need at least R specified if you define it yourself, otherwise the manpage may look garbled (#191). Thanks to Yukai Chou for suggesting.PAGER or MANPAGER is set but empty; fallback to pager discovery (#194). For example this prevented to see manpages in emacs's compilation mode which unhelpfully hardcodes PAGER="".stderr with styled text (#144). Quoted and typewriter text is in bold. Variables are written as underlines. Key words of error messages are in red.Try with $(tool) --help for more information message. Instead we explicitly indicate the --help option in the usage line. Having the error message at the end makes it easier to spot.--help request work in any context, except after -- or on the arguments after an unknown command error in which case that error is reported (less confusing). Since the option has an optional argument value, one had to be carefull that it would not pickup the next argument and try to parse it according to FMT. This is no longer the case. If the argument fails to parse --help=auto is assumed. (#201).--__complete option for library use.$(cmd), $(cmd.name) and $(tool) can be used and should be prefered over of $(iname), $(tname) and $(mname). $(cmd.parent) is added to refer to a command's parent or itself at the root.Cmdliner.Arg.conv abstract. Thanks to Andrey Popp for the patch (#206).docv parameter of argument converters can now be used to define the default value used by docv in Arg.info. See Arg.Conv.docv.Manpage.section_name type alias (#202).Cmd.make which should be preferred to Cmd.v (The M.v notation is nice for simulating literals, not for heavy constructor).Cmd.Env.info_var. To get back the environment variable name from a variable info.doc_envs argument to Arg.info for adding the given environment variables info to the command in which the argument is used. Sometimes more than one variable make sense and the env argument is not directly used.Arg.Completion a module to define argument completion strategies (#1, #187).Arg.Conv module to define converters. This should be used in new code.Arg.{file,dir,}path string converters equiped with appropriate file system completions.docv optional parameter to Arg.enum.Term.env which provides access to the environment access function provided to evaluation functions.deprecated argument of Cmdliner.Cmd.info, Cmdliner.Arg.info and Cmdliner.Cmd.Env.info. First, the language markup is now supported therein. Second the message is no longer only used to warn about usage it is now also prepended to the doc string of the entity.Arg.conv's docv property in the documentation of arguments whenever Arg.info's docv is unspecified (#207).- in Arg.file or Arg.non_dir_file values. This is supposed to mean stdin or stdout (#208).Sys.getenv in Cmd.eval* functions instead of calling the env argument as advertised in the docs. Incidentally add an env optional argument to Manpage.print (#209).Arg.{printer,conv_docv,conv_parser, conv_printer,parser_of_kind_of_string,conv,conv'}. These will likely never be removed but they should no longer be used for new code. Use Arg.Conv.Arg.{converter,parser,pconv} (#206).Arg.{env,env_var} (#206).Term.{pure,man_format} (#206).Term evaluation interface (#206).cmdliner tool to help with manpage and completion script installation. See the command line interface manual of the library for more information (#187, #227, #228).odoc and goto definition editor functionality. Thanks to Emile Trotignon and Paul-Elliot Anglès d'Auriac for noticing and suggesting (#225).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 subcommand support to allow arbitrarily nested subcommands 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 subcommands 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 subcommands as positional arguments you will effectively break the command line compatibility of your tool since options can no longer be specified before the subcommands, 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.