Positional arguments help output

[vanboxem.ruben@…]

Currently, there is no way to output positional argument descriptions. This is however often useful as special values of these options may have special results.

I originally asked the question on ​Stackoverflow.

Summarizing the question linked above, I'd like for this kind of output to be readily available:

cmp: compare two files
Usage: cmp [ -l | -s ] file1 file2
Options:
  --help                Show this help output.
  -l                    (Lowercase ell.) Write the byte number (decimal) and the differing bytes (octal) for each difference.
  -s                    Write nothing for differing files; return exit status only.
Operands:
  file1                 A pathname of the first file to be compared. If file1 is '-', the standard input shall be used.
  file2                 A pathname of the second file to be compared. If file2 is '-', the standard input shall be used.

where file1 and file2 are pure positional arguments that have behavior warranting a full description.

I propose a simple and backwards-compatible change to the way positional_argument_description works:

po::positional_options_description operands("operands");
operands.add("file1", 1, "A pathname of the first file to be compared. If file1 is '-', the standard input shall be used.")
operands.add("file2", 1, "A pathname of the second file to be compared. If file2 is '-', the standard input shall be used.");

1. Add an optional string argument to the constructor and store it like for normal program_descriptions
2. Add a third optional argument containing the description string of the positional argument
3. Provide an operator<< overload that would allow for formatted output like the above.