Convention for command help

[Gustavo Niemeyer]

H there,

I just went through a few branches and noticed that we're still slightly
mixed up on the conventions for command help.

Since we're just doing the migration from the "snappy" command into "snap",
this is a good time for us to get a more consolidated view on that.

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

- Short help: starts with a verb, inline, no punctuation:

var shortAssertHelp = i18n.G("Adds an assertion to the system.")

- Long help: starts with "The <name> command", backquoted broken out lines,
proper punctuation:

var longAssertHelp = i18n.G(`
The assert command attempts to add the assertion in the provided file
to the system assertion database. (...)
`)

The longAssertHelp will likely have to be stripped out of its leading
newline, but I suggest we keep the format like that, both to make reading
the likely display result easier, and to encourage slightly more
descriptive user-oriented comments on our commands.

Sounds reasonable?


gustavo @ http://niemeyer.net
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/snappy-devel/attachments/20160203/215ee4fd/attachment.html>