Allow insertion of arbitrary top-level text before and after list of options in help text

[Adrianna Pińska]

Many utilities have --help output which includes paragraphs of text at the top level before and/or after the list of options. This is used to convey general information which is not specific to a particular option. I haven't found an option for this in cxxopts.

[Slaven Falandys]

I have similar problem.

Take this code snippet for example:

cxxopts::Options options("test", "A brief description");

options.add_options()
    ("b,bar", "Param bar", cxxopts::value<std::string>())
    ("d,debug", "Enable debugging", cxxopts::value<bool>()->default_value("false"))
    ("f,foo", "Param foo", cxxopts::value<int>()->default_value("10"))
    ("h,help", "Print usage")
;

std::cout << options.help() << std::endl;

Output will be this:

A brief description
Usage:
  test [OPTION...]

  -b, --bar arg  Param bar
  -d, --debug    Enable debugging
  -f, --foo arg  Param foo (default: 10)
  -h, --help     Print usage

I would like that options.help() returns only this:

  -b, --bar arg  Param bar
  -d, --debug    Enable debugging
  -f, --foo arg  Param foo (default: 10)
  -h, --help     Print usage

I workaround this problem by taking result of options.help() and removing first four lines to get desired text.
There are several reason for this:

1. My application can be used in different ways.
2. I would like to have multiline description text between usage string and option descriptions.
3. I think that class cxxopts::Options does not need to know application name and description. Class cxxopts::Options should know only about allowed options.

For example, see output of chmod --help:

Usage: chmod [OPTION]... MODE[,MODE]... FILE...
  or:  chmod [OPTION]... OCTAL-MODE FILE...
  or:  chmod [OPTION]... --reference=RFILE FILE...
Change the mode of each FILE to MODE.
With --reference, change the mode of each FILE to that of RFILE.

  -c, --changes          like verbose but report only when a change is made
  -f, --silent, --quiet  suppress most error messages
  -v, --verbose          output a diagnostic for every file processed
...

I would like to hear some comments.