Display multi-line examples with trailing indents to enhance readability

[roryokane]

Problem

My CLI defines two examples, and one of them has both a long command and a long description. Here is a simplified version of my yargs setup:

const yargsArgv = require("yargs")
  .example("$0 myTranscribeFile.xsc", "reading input with a file argument")
  .example(
    "cat myTranscribeFile.xsc | $0 > transcribeFileData.json",
    "converting input with stdin and stdout redirection"
  )
  .help().argv

When I run ts-node index.ts --help (indirectly through a script in package.json), the output looks like this:

Usage: index.ts [option] [file]

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

Examples:
  index.ts myTranscribeFile.xsc             reading input with a file argument
  cat myTranscribeFile.xsc | index.ts >     converting input with stdin and
  transcribeFileData.json                   stdout redirection

The problem is in the Examples section, it looks like there are three examples – the second one is cat myTranscribeFile.xsc | index.ts > and the last one is transcribeFileData.json.

Solution

This problem could be avoided by indenting all lines after the first line (i.e. adding a trailing indent) in multi-line examples, in both the command part and the description part:

Examples:
  index.ts myTranscribeFile.xsc             reading input with a file argument
  cat myTranscribeFile.xsc | index.ts >     converting input with stdin and
    transcribeFileData.json                   stdout redirection

Implementation

I looked in the code of yargs, and I see that these steps are needed to implement this:

• [ ] Add support for trailing indents to cliui’s div function (https://github.com/yargs/cliui/issues/77)
  • For example, support an option multilineIndents for each column that takes an array of two numbers [leadingIndent, trailingIndent].
• [ ] Update the two relevant ui.div calls in lib/usage.ts to use trailing indents
  • If the new option were multilineIndents as described above, this change would consist of adding multilineIndents: [0, 2], to the options for all three columns within those two ui.div calls.

Wider applicability

So far I haven’t seen this problem of confusing wrapped lines anywhere but in my Examples section. But I wonder if any of the other Yargs sections are susceptible to a similar readability problem. If so, maybe trailing indents could fix readability in those sections too.

[Nantris]

Is there any way to achieve this? We need to add a usage caveat and a new line would be the ideal place to put it.

[bcoe]

@Slapbox I could imagine people wanting both formats, what if we made this a config setting?

https://github.com/yargs/yargs/blob/main/docs/api.md#parserconfigurationobj

[Nantris]

@bcoe I think that would be fine, but I can't say I fully understand the implications for other cases where we want the automatic formatting to do its thing.