Controlling help output

GLI's help output is fairly opinionated, but does offer some amount of control of formatting, if your app should need it.

SYNOPSIS

The "synopsis" is the area of the help indicating command-line usage in a general sense. When subcommands were added, this area was expanded to show subcommand-specific arguments in the synopsis, like so:

SYNOPSIS
  todo [global options] list [command options] tasks [-l|--long] [-x|--completed] [args]

When creating a complex application, this can get unwieldy, so you can exert some limited control via the synopsis_format:

:full (default)

This will show the full synopsis as described above, always.

:compact

This will always show a "compact" version, like so:

SYNOPSIS
  todo [global options] list [command options] tasks [subcommand options] [args]

:terminal

This will use :full if the synopsis can fit in the existing terminal, and :compact if it cannot.

Order of commands in output

By default, GLI sorts commands or subcommands alphabetically, however you can sort them in the order declared by using sort_help

sort_help :manually

Text Wrapping

By default, GLI wraps text from your desc or long_desc to the width of the terminal and breaks paragraphs, however you can configure it to show formatted help verbatim, or to bring all text to a single, unwrapped line.

This is controlled via the directive wrap_help_text:

wrap_help_text :verbatim

There four supported wrapping modes:

:to_terminal (the default)

Wrap lines on a word boundary at terminal width. Single newlines become spaces and double newlines become paragraphs:

c.long_desc %{This is a very long description
of a command that is important.

You should use it
for all your needs}

For a terminal of 40 characters in width, produce this:

This is a very long description of a
command that is important.

You should use it for all your needs

Note that if you redirect help output to a file, it will still format this way. See tty_only

:one_line

Here, the output is "unwrapped", and sucked up onto a single line, regardless of any newlines.

c.long_desc %{This is a very long description
of a command that is important.

You should use it
for all your needs}

produces this:

This is a very long description of a command that is important. You should use it for all your needs

:verbatim

This will preserve an formatting you have. This is most useful for creating ascii-art tables or other specific formatting. Note that although GLI will not wrap your text, your terminal emulator may, if the text is wider than the terminal. It's probably safest to manually wrap your verbatim text at 80 characters.

c.long_desc %{
This will be a formatted description:
  - all formatting
  - will be preserved

--------------
| including  |
+------------+
| ascii art  |
--------------
}

produces:

This will be a formatted description:
  - all formatting
  - will be preserved

--------------
| including  |
+------------+
| ascii art  |
--------------

:tty_only

This will wrap as :to_terminal if the output is a TTY/Terminal but if the output is going to a file or pipe, will use :one_line.