Configuring help and usage messages
***********************************

The usage and help messages of parsers and commands can be generated
on demand using ":get_usage()" and ":get_help()" methods, and
overridden using "help" and "usage" properties. When using the
autogenerated usage and help messages, there are several ways to
adjust them.


Hiding arguments, options, and commands from messages
=====================================================

If "hidden" property for an argument, an option or a command is set to
"true", it is not included into help and usage messages, but otherwise
works normally.

   parser:option "--normal-option"
   parser:option "--deprecated-option"
      :hidden(true)

   $ lua script.lua --help

   Usage: script.lua [-h] [--normal-option <normal_option>]

   Options:
      -h, --help            Show this help message and exit.
      --normal-option <normal_option>

   $ lua script.lua --deprecated-option value

   {
      deprecated_option = "value"
   }


Hiding option and command aliases
=================================

Hidden aliases can be added to an option or command by setting the
"hidden_name" property. Its value is interpreted in the same way as
the "name" property.

   parser:option "--server"
      :hidden_name "--from"

   $ lua script.lua --help

   Usage: script.lua [-h] [--server <server>]

   Options:
      -h, --help            Show this help message and exit.
      --server <server>

   $ lua script.lua --server foo
   $ lua script.lua --from foo

   {
      server = "foo"
   }


Setting argument placeholder
============================

For options and arguments, "argname" property controls the placeholder
for the argument in the usage message.

   parser:option "-f" "--from"
      :argname "<server>"

   $ lua script.lua --help

   Usage: script.lua [-h] [-f <server>]

   Options:
      -h, --help            Show this help message and exit.
      -f <server>, --from <server>

"argname" can be an array of placeholders.

   parser:option "--pair"
      :args(2)
      :argname {"<key>", "<value>"}

   $ lua script.lua --help

   Usage: script.lua [-h] [--pair <key> <value>]

   Options:
      -h, --help            Show this help message and exit.
      --pair <key> <value>


Grouping elements
=================

":group(name, ...)" method of parsers and commands puts passed
arguments, options, and commands into a named group with its own
section in the help message. Elements outside any groups are put into
a default section.

   parser:group("Configuring output format",
      parser:flag "-v --verbose",
      parser:flag "--use-colors",
      parser:option "--encoding"
   )

   parser:group("Configuring processing",
      parser:option "--compression-level",
      parser:flag "--skip-broken-chunks"
   )

   parser:flag "--version"
      :action(function() print("script.lua 1.0.0") os.exit(0) end)

   $ lua script.lua --help

   Usage: script.lua [-h] [-v] [--use-colors] [--encoding <encoding>]
          [--compression-level <compression_level>]
          [--skip-broken-chunks] [--version]

   Configuring output format:
      -v, --verbose
      --use-colors
      --encoding <encoding>

   Configuring processing:
      --compression-level <compression_level>
      --skip-broken-chunks

   Other options:
      -h, --help            Show this help message and exit.
      --version


Help message line wrapping
==========================

If "help_max_width" property of a parser or a command is set, when
generating its help message, argparse will automatically wrap lines,
attempting to fit into given number of columns. This includes wrapping
lines in parser description and epilog and descriptions of arguments,
options, and commands.

Line wrapping preserves existing line endings and only splits overly
long input lines. When breaking a long line, it replicates indentation
of the line in the continuation lines. Additionally, if the first non-
space token in a line is "*", "+", or "-", the line is considered a
list item, and the continuation lines are aligned with the first word
after the list item marker.

   parser:help_max_width(80)

   parser:option "-f --foo"
      :description("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor " ..
         "incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation " ..
         "ullamco laboris nisi ut aliquip ex ea commodo consequat.\n" ..
         "The next paragraph is indented:\n" ..
         "  Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. " ..
         "Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.")

   parser:option "-b --bar"
      :description("Here is a list:\n"..
         "* Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor...\n" ..
         "* Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip...\n" ..
         "* Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.")

   $ lua script.lua --help

   Usage: script.lua [-h] [-f <foo>] [-b <bar>]

   Options:
      -h, --help            Show this help message and exit.
         -f <foo>,          Lorem ipsum dolor sit amet, consectetur adipiscing
      --foo <foo>           elit, sed do eiusmod tempor incididunt ut labore et
                            dolore magna aliqua. Ut enim ad minim veniam, quis
                            nostrud exercitation ullamco laboris nisi ut aliquip ex
                            ea commodo consequat.
                            The next paragraph is indented:
                              Duis aute irure dolor in reprehenderit in voluptate
                              velit esse cillum dolore eu fugiat nulla pariatur.
                              Excepteur sint occaecat cupidatat non proident, sunt
                              in culpa qui officia deserunt mollit anim id est
                              laborum.
         -b <bar>,          Here is a list:
      --bar <bar>           * Lorem ipsum dolor sit amet, consectetur adipiscing
                              elit, sed do eiusmod tempor...
                            * Ut enim ad minim veniam, quis nostrud exercitation
                              ullamco laboris nisi ut aliquip...
                            * Duis aute irure dolor in reprehenderit in voluptate
                              velit esse cillum dolore eu fugiat nulla pariatur.

"help_max_width" property is inherited by commands.


Configuring help and usage message layout
=========================================

Several other parser and command properties can be used to tweak help
and usage message format. Like "help_max_width", all of them are
inherited by commands when set on the parser or a parent command.

"usage_max_width" property sets maximum width of the usage string.
Default is "70".

"usage_margin" property sets margin width used when line wrapping long
usage strings. Default is "7".

   parser:usage_max_width(50)
      :usage_margin(#"Usage: script.lua ")

   parser:option "--foo"
   parser:option "--bar"
   parser:option "--baz"
   parser:option "--qux"

   print(parser:get_usage())

   $ lua script.lua

   Usage: script.lua [-h] [--foo <foo>] [--bar <bar>]
                     [--baz <baz>] [--qux <qux>]

Help message for a group of arguments, options, or commands is
organized into two columns, with usage template on the left side and
descriptions on the right side. "help_usage_margin" property sets
horizontal offset for the first column ("3" by default).
"help_description_margin" property sets horizontal offset for the
second column ("25" by default).

"help_vertical_space" property sets number of extra empty lines to put
between descriptions for different elements within a group ("0" by
default).

   parser:help_usage_margin(2)
      :help_description_margin(17)
      :help_vertical_space(1)

   parser:option("--foo", "Set foo.")
   parser:option("--bar", "Set bar.")
   parser:option("--baz", "Set baz.")
   parser:option("--qux", "Set qux.")

   $ lua script.lua --help

   Usage: script.lua [-h] [--foo <foo>] [--bar <bar>] [--baz <baz>]
          [--qux <qux>]

   Options:

     -h, --help     Show this help message and exit.

     --foo <foo>    Set foo.

     --bar <bar>    Set bar.

     --baz <baz>    Set baz.

     --qux <qux>    Set qux.
