dbuenzli / cmdliner

Declarative definition of command line interfaces for OCaml
http://erratique.ch/software/cmdliner
ISC License
296 stars 56 forks source link

EXIT STATUS section, mention the full command rather than only the sub command. #168

Closed Alizter closed 1 year ago

Alizter commented 1 year ago

When printing the doc for the exit code statuses the following is used:

`P "$(tname) exits with the following status:"
31

There are two issues here:

  1. status should be statuses since there is more than one exit code in most cases.
  2. The full command name is not printed, but rather the subcommand. For instance
  EXIT STATUS
         rpc exits with the following status:

should rather be

  EXIT STATUS
         dune rpc exits with the following status:
dbuenzli commented 1 year ago
  1. status should be statuses since there is more than one exit code in most cases.

I disagree, using statuses would convey that it is possible to exit with more than one status. You should read the preamble sentence and each case as a declaration.

Alizter commented 1 year ago

Then perhaps it should be:

         rpc exits with one of the following statuses:
dbuenzli commented 1 year ago

But then you need to deal with singular and plural.

Alizter commented 1 year ago

Is it likely that it is ever singular however? That seems to be an edge case here.

dbuenzli commented 1 year ago

Well you won't be the person who gets an issue the day a user of the library falls on the case and decides to report it…

dbuenzli commented 1 year ago

Regarding 1. I simplified the default EXIT STATUS wording to $(iname) exits with: which works with both singular and plural.

Alizter commented 1 year ago

Thanks!