[Feature] Tagline in help text

[bojavou]

Hello! I'd like to include a tagline in the help text. Maybe with a description function.

yargs(..)
  .scriptName('gadget')
  .description('Never eat a pirate. He'll spend the rest of his after hunting you.')

gadget <command>

Never eat a pirate. He'll spend the rest of his afterlife hunting you.

Commands:
  gadget mix   Mix it up well
  gadget stir  Stir a little

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]

Not enough non-option arguments: got 0, need at least 1

You can kind of do it with usage(), but it shows up in the commands list which I don't want.

yargs(..)
    .scriptName('gadget')
    .usage('$0 <command>', 'Never eat a pirate. The indigestion is terrible.')

gadget <command>

Never eat a pirate. The indigestion is terrible.

Commands:
  gadget <command>     Never eat a pirate. The indigestion is terrible.[default]
  gadget mix           Mix it up well
  gadget stir          Stir a little

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]

Not enough non-option arguments: got 0, need at least 1

The epilog is also nice but it puts it at the end. I'd rather it have right up at the top as a nice header.

yargs(..)
  .scriptName('gadget')
  .epilog('Never eat a pirate. Zombies are much tastier.')

gadget <command>

Commands:
  gadget mix   Mix it up well
  gadget stir  Stir a little

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]

Never eat a pirate. Zombies are much tastier.

Not enough non-option arguments: got 0, need at least 1

[bojavou]

Submitted some code in #2338, to give it something real for discussion.

[shadowspawn]

My initial impression is that usage() is the right method for setting the command usage and description.

But .usage() is also used as an alias for ".command()` and setting the default command, as you discovered.

I wonder if the default-command behaviour should only be triggered if there is a builder or handler? (Would this break any reasonable legacy use cases?)

[shadowspawn]

Having second thoughts about overloading .usage()! It might fit into the existing api but is not a direct match for the goal.

A method called .desc() or .description() would be more explicit. In practice it will usually only be called on the top-level command since the methods for creating subcommands have a description parameter.

desc is not as nice to read, but matches the property name when a subcommand is created using a json description. (The property exported from a module used with .commandDir() is describe, but .describe() is used for describing options and positionals.)

(I need to do some more reading in the existing API to get a better idea of the existing patterns.)

[shadowspawn]

desc is not as nice to read, but matches the property name when a subcommand is created using a json description.

Red herring, the code supports desc or describe or description! Ref: #917

[shadowspawn]

I do see the subcommand description displayed in subcommand help in a very simple test program, but the description goes away when I add a custom usage. I see in #1830 (comment) that the subcommand description is actually not intended to be displayed in the subcommand help. So this is in line with what you thought, that the description is intended to appear in the list of subcommands.

I note that a few of the example files put extra lines into the usage string. So that looks like the simple and historical work-around.

yargs/example/line_count_options.js

Line 3 in e517318

.usage('Count the lines in a file.\nUsage: $0')

(Rather more complicated question than I expected!)