Convention for command help text

snapd
1

Hello all,

I’m bringing here the following text from an ancient topic in the old mailing list, which proposes a convention for how we should phrase the help text for the various commands and how that code should look like.

We’re doing much better by now, but we’re still inconsistent in a few places. So let’s see if we can eventually converge.

Here is a proposal, taking the assert command as an example.

Short help

Starts with a verb in second person imperative, inline, no punctuation.

Example:

var shortAssertHelp = i18n.G(`Add an assertion to the system`)

Long help

Starts with a short sentence that must begin with “The <name> command …”, in third person indicative, backquoted, broken out lines [wrapped at 79 columns], proper punctuation.

Example:

var longAssertHelp = i18n.G(`
The ack command tries to add an assertion to the system assertion database.

The assertion may also be a newer revision of a preexisting assertion that
it will replace.
`)

The longAssertHelp will be stripped out of its leading newline[, and wrapped to fit the terminal].

2

@snapd Quick reminder for us to pay attention to this. Looking at snap help, looks like the convention derailed again.

3

* rewrites everything in subjunctive

4

In all seriousness, we do do this, but we’re using different tenses and it’s not that nice. In particular your example uses third person indicative, and I personally think it’d be better to use second person imperative. Things are split right now¹, and just to be clear, I care very little about which tense we use as long as it’s unified, but to me imperative is a more natural tense in which to issue commands, and it has two small advantages over indicative, one that might be exclusive to English:

  • it a little bit shorter, and avoids the slightly cacophonic ending that indicative can have.
  • it reflects the fact that things can fail (indicative is for facts… :slight_smile:)

And that’s all I have to say about that.

1:

$ snap help | awk 'cmd {print $2}; /^Available commands:/{cmd=1}' | sort | uniq -c | sort -g
      1 Abort
      1 Adds
      1 Authenticates
      1 Buys
      1 Changes
      1 Connects
      1 Disables
      1 Disconnects
      1 Downloads
      1 Enables
      1 Finds
      1 Help
      1 Installs
      1 Log
      1 Pack
      1 Prefer
      1 Query
      1 Refreshes
      1 Removes
      1 Restart
      1 Retrieve
      1 Reverts
      1 Run
      1 Sets
      1 Show
      1 Start
      1 Stop
      1 Switches
      1 Tests
      1 Unalias
      1 Watch
      2 Prints
      2 Shows
      3 List
      3 Lists
5

We’re perfectly aligned here. This was just the historical recommendation, but as long as we have something consistent I’m also happy. If you’d prefer something else, please feel free to edit the top message, and also to transform it into something less personal and that reads better as a current recommendation on the way.