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.
Starts with a verb in second person imperative, inline, no punctuation.
var shortAssertHelp = i18n.G(`Add an assertion to the system`)
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.
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].