USAGE statements should be formatted by default

[tbrowder]

The Problem

Users at the command line interface (CLI) expect help to be usable. Currently the output from Raku programs taking advantage of MAIN and USAGE splatter across the terminal in a clutter of long lines wrapped according to the settings of the terminal.

Expected Behavior

As a minimum, lines should be neatly formatted with lines wrapped at a conventional value such as 70 or 72 characters. Ideally, a long line that is so wrapped would have succeeding lines indented to indicate such wrapping.

Actual Behavior

As an example of current behavior take the following steps in a terminal window:

$ zef install Documentable
$ documentable --help
...lots of text...

[coke]

One of Documentable's dependencies is failing to install (perl6/Pod-To-Cached#22) - Can you include the actual output?

[tbrowder]

$ documentable --help
Usage:
  documentable setup [-y|--yes] -- Downloads default assets to generate the site
  documentable start [--topdir=<Str>] [--conf=<Str>] [-v|--verbose] [-p|--primary] [-s|--secondary] [--search-index] [-i|--indexes] [-t|--typegraph] [-f|--force] [--highlight] [--typegraph-file=<Str>] [--highlight-path=<Str>] [--dirs=<Str>] [-a|--all] -- Start the documentation generation with the specified options
  documentable update [--topdir=<Str>] [--conf=<Str>] [-v|--verbose] [--highlight] [--highlight-path=<Str>] -- Check which pod files have changed and regenerate its HTML files.
  documentable clean -- Delete files created by "documentable setup"
  documentable [-V|--version] -- Documentable version
  
    -y|--yes                  Always accept the operation (to use in scripts)
    --topdir=<Str>            Directory where the pod collection is stored
    --conf=<Str>              Configuration file
    -v|--verbose              Prints progress information
    -p|--primary              Generates the HTML files corresponding to primary objects
    -s|--secondary            Generates per kind files
    --search-index            Generates the search index
    -i|--indexes              Generates the index files
    -t|--typegraph            Write typegraph visualizations
    -f|--force                Force the regeneration of the typegraph visualizations
    --highlight               Highlights the code blocks
    --typegraph-file=<Str>    TypeGraph file
    --highlight-path=<Str>    Path to the highlighter files
    --dirs=<Str>              Dirs where documentation will be found. Relative to :$topdir
    -a|--all                  Equivalent to -t -p -s -i --search-index

[coke]

Some notes and questions from my perspective:

• I regularly use 120 characters, so this output looks mostly fine there (but still one line that's long).
• Is there prior art from other languages? Do they default to assuming 80?
• Could we dynamically check the size of the screen where possible before assuming a default?
• Moving the description to above/below a line of options would give us more space.
• Line wrapping means we break cut and paste of the suggested command line.

[tbrowder]

Prior art:

• The GNU Coding Standards mentions in formatting source code lines should be 79 characters or less.

• The current Raku compiler '--help' text has a maximum line length of 84 characters. [text emmitted to users]

• Our 'CONTRIBUTING.md' text mention a maximum line length of 76 characters for a commit mesage. [text emitted to users]

[coke]

That is a separate issue: source code formatting isn’t the same as formatting of diagnostics emitted to the users.

[MasterDuke17]

Linus Torvalds had some recently commentary (that I mostly agree with) about 80 char line limits. https://lkml.org/lkml/2020/5/29/1038

[tbrowder]

Linus is known for his absolute control of his products--very autocratic and opinionated.

[codesections]

@tbrowder wrote:

As a minimum, lines should be neatly formatted with lines wrapped at a conventional value such as 70 or 72 characters.

@coke wrote:

I regularly use 120 characters, so this output looks mostly fine there

The way to produce output that looks good to both of you is to check the width of the user's terminal and wrap text based on that width. Unless someone objects, I'll prepare a PR adding that behavior.