OSTREE(1) 'man' page

[Ricky-Tigg]

Tacit convention

SYNOPSIS

'{MAIN_COMMAND} {COMMAND} [OPTIONS]'

For example The syntax 'ostree {COMMAND} [OPTIONS...]' conforms to common usage observed in 'man' pages, according to which the main command is invariably not interpreted as '{COMMAND}' since it is required by default—a tacit convention, in short. Without such usage, the syntax would be as follows:

'{COMMAND} {SUBCOMMAND} [OPTIONS]'

where 'ostree' would be as the '{COMMAND}'.

---

Hello. Notes on OSTREE(1)

Options

'--version'

As is customary in projects designed with CLI support, this option, when it exists, holds a privileged position, being incompatible with a command and taking precedence over it if invoked with it. For example, 'ostree admin status --version' prints only the text resulting from this option. Consequently, the mention of such a characteristic in project documentation is so often deliberately omitted.

However, for any other option with this characteristic, it is customary to mention it. This is the case, for example, for 'OSTREE ADMIN(1)' in the 'man' page, with respect to the '--print-current-dir' option. It also provides information on this, like this: "This is incompatible with specifying a subcommand."

$ ostree admin status --print-current-dir
/ostree/deploy/fedora/deploy/[sha256].0

'--verbose'

This option may well have been designed to have a global application. If so, it would be good to mention it under a section typically presented as 'Global options'.

'--repo'

Mentioning it in this manual is an unfortunate choice, as it leads to the following interpretation:

Since each of the commands that require this option specifies it in its dedicated 'man' page and '--help' section, applying the SYNOPSIS leads to doubling the '--repo' specification in the command formulation:

'ostree {COMMAND} --repo'

where '--repo' is as '[OPTIONS]' of 'ostree'.

Which formulation in turn develops into this:

'ostree {COMMAND} --repo --repo'

where the second '--repo' is as '[OPTIONS]' of '{COMMAND}'.

Which final command is then invalid.

Commands

 System administrators will primarily interact with OSTree via
 the subcommand ostree admin.

Sticking to the SYNOPSIS, doesn't the formulation "subcommand ostree admin" lack consistency? According to this, 'admin' would be a subcommand of '{COMMAND}' and not itself a '{COMMAND}'.