Add: cmdliner.1.1.0

[dbuenzli]

• Add: cmdliner.1.1.0 home, doc, issues
  Declarative definition of command line interfaces for OCaml

---

cmdliner v1.1.0 2022-02-06 La Forclaz (VS)

• Require OCaml 4.08.

• Support for deprecating commands, arguments and environment variables (#66).
  See the ?deprecated argument of Cmd.info, Cmd.Env.info and Arg.info.

• Add Manpage.s_none a special section name to use whenever you
  want something not to be listed in a command's manpage.

• Add Arg.conv' like Arg.conv but with a parser signature that returns
  untagged string errors.

• Add Term.{term,cli_parse}_result' functions.

• Add deprecation alerts on what is already deprecated.

• On unices, use command -v rather than type to find commands.

• Stop using backticks for left quotes. Use apostrophes everywhere.
  Thanks to Ryan Moore for reporting a typo that prompted the change (#128).

• Rework documentation structure. Move out tutorial, examples and
  reference doc from the .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).

• The deprecated 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:

  1. They were not escaped, they now are.
  2. They where not rendered in bold, they now are.
  3. The documentation language was interpreted, it is no longer the case.

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

• Documentation generation use: … (U+2026) instead of ... for
  ellipsis. See also UTF-8 manpage support below.

• Documentation generation, improve command synopsis rendering on
  commands with few options (i.e. mention them).

• Documentation generation, drop section heading in the output if the section
  is empty.

New Cmd module and deprecation of the Term evaluation interface

This 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:

  • The ?exits argument which defaults to Cmd.Exit.defaults
    rather than the empty list.
  • The ?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).
  • The ?sdocs argument which defaults to Manpage.s_common_options
    rather than Manpage.s_options.

• The 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.

• If you relied on ?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 explicitely 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.

UTF-8 manpage support

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

to:

NROFF       /usr/bin/mandoc -Tutf8 -c

Thanks to Antonin Décimo for his knowledge and helping with these
mangnificent intricacies (#27).

---

Use b0 cmd -- .opam.publish cmdliner.1.1.0 to update the pull request.

[dbuenzli]

The number of failures is abnormally high. This was supposed to be a mostly compatible release. Let me investigate that.

[dbuenzli]

Ok I tripped out a little bit too quickly. There's also a lot of stuff that does actually succeed. It seems most errors are due to dbuenzli/cmdliner#124 which was proposed by @talex5.

I think it's good to keep @talex5's proposal. A lot of these failures use Term.exit @@ Term.eval t with a term t that evaluates to an int thinking (and who can blame them?) it will exit with that code while it will simply exit with 0. I'm glad this confusing API is deprecated by the new release.

I propose to let the CI finish and then I will adjust with a first round of constraints – still longing for ocaml/opam#3077 btw :–).

[dbuenzli]

So I have put a first round of constraints using this technique.

[dbuenzli]

Is the CI stuck ? Looking at the current state it seems I missed:

[coin.0.1.0 (failed: The type of this expression,)](https://opam.ci.ocaml.org/github/ocaml/opam-repository/commit/7a64abb7c9699c60fe192f7b6114624a288dcfa7/variant/opam-2.0,compilers,4.08,coin.0.1.0)
[coin.0.1.1 (failed: The type of this expression,)](https://opam.ci.ocaml.org/github/ocaml/opam-repository/commit/7a64abb7c9699c60fe192f7b6114624a288dcfa7/variant/opam-2.0,compilers,4.08,coin.0.1.1)
[uuuu.0.1.0 (failed: The type of this expression,)](https://opam.ci.ocaml.org/github/ocaml/opam-repository/commit/7a64abb7c9699c60fe192f7b6114624a288dcfa7/variant/opam-2.0,compilers,4.08,uuuu.0.1.0)
[uuuu.0.1.1 (failed: The type of this expression,)](https://opam.ci.ocaml.org/github/ocaml/opam-repository/commit/7a64abb7c9699c60fe192f7b6114624a288dcfa7/variant/opam-2.0,compilers,4.08,uuuu.0.1.1)

Should I simply constraint these and then let you merge it without yet another melting planet CI run ?

[kit-ty-kate]

i'll redo the constraints manually in a separate PR later today.
Using a script parsing the CI reault isn't right as this does not take cases where only the dependencies of these packages are failing, into account

[dbuenzli]

Using a script parsing the CI reault isn't right as this does not take cases where only the dependencies of these packages are failing, into account

Not sure I'm getting this. No non-existing cmdliner dependency has been added by this PR (the script was selecting certain errors).

[kit-ty-kate]

CI doesn't make the difference between "my dependency failed" and "the package i was trying to build" or even "this package built fine but only the tests failed.
To know the difference you have to look into the logs, which the script doesn't and opam admin add-constraint doesn't know either

[dbuenzli]

I see, that's a bit unfortunate.

Are there any plans to make the distinction ? I guess it should all start with making opam return appropriate exit codes no ?

To know the difference you have to look into the logs,

Quoting from memory, in the previous run there were something like 800 failures out of 8000 runs. I doubt that's manageable by hand.

Maybe you can simply try to manually inspect the packages that I constrained here (which all did fail because they had cmdliner dependency) that have a dependency that depends on cmdliner.

[dbuenzli]

Can we move on this ? (If there's stuff I can do, tell me)

[kit-ty-kate]

With #20686 and #20687 all the errors seem to be gone.

pinging some of the maintainers affected by the change of API: @NathanReb, @craigfe, @dinosaure, @Leonidas-from-XIV, @gpetiot, @hannesm

[kit-ty-kate]

Thanks!

[dbuenzli]

Thanks @kit-ty-kate for the tremendous help on this.

[dbuenzli]

Btw. people like @gpetiot are not affected by the API their package tests fails. Please do not test the error or manpage outputs of cmdliner in the ocaml-repository they are not meant to be stable across versions.

[Leonidas-from-XIV]

@kit-ty-kate Ah. Yes. I've stumbled into the exact issue that @talex5 reported so I am kinda happy that this is fixed now because I tripped over it myself just this year. I guess we'll update dune-release and MDX to use cmdliner >= 1.1.0 going forward.