id,summary,reporter,owner,description,type,status,milestone,component,version,severity,resolution,keywords,cc
8430,Positional arguments help output,vanboxem.ruben@…,Vladimir Prus,"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 [http://stackoverflow.com/questions/15863056/how-to-display-commandline-operand-description-in-help-output 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.
",Feature Requests,new,To Be Determined,program_options,Boost 1.53.0,Problem,,,