[boost] [program_options] multi-line description patch

From: Bertolt Mildner (Bertolt.Mildner_at_[hidden])
Date: 2004-12-03 20:18:04

What do you think about the attached patch to enable correct formated
multi-line option descriptions?

It is not pretty but is has the following features:
- Formats multi-line descriptions using first_column_width and a given line
length (currently hardcoded).

- If set up for a shell with 80 chars per line it uses only 79 *but* also
formats correctly in larger shells.

- Handles '\n' in description strings.

- Trimms leading *single* spaces in new lines (" that" gets trimmed, but "
leave my formatting" not).

- Words are not chopped at line endings but put to new line (if not more
that half the line would be empty).

Known problems:
- If the current shell has too short lines the formatting is all messed up.

- Chokes on '\t', they are currently not handled in any way.

- Sacrifices one char to be able to format correctly in larger shells.

- Code is a "iterator arithmetic" hell. :(

- The line length should be a parameter of options_description with a
default value (probably 80).
  With this users may query the current shell for its line length, if
possible.

Patch compiles fine on CW 8.3 and VC 7.1.

Maybe heaving two modes would also be a good idea? One as a "safe mode"
where one char is sacrifices but the line length may be longer and another
mode where the exact line length is known and fully used ...

The following code ...
----------------------------------------------------------
    po::options_description options("Options");

    options.add_options()
      ("help", "a long help msg a long help msg a long help msg a long help
msg a long help msg a long help msg a long help msg a long help msg ")
      ("well_formated", "As you can see this is a very well formatted
option description.\n"
                        "You can do this for example:\n\n"
                        "Values:\n"
                        "  Value1: does this and that\n"
                        "  Value2: does something else\n"
                        "  Value3: has a very long\n
description.")
      ;

    std::cout << options << "\n";

----------------------------------------------------------

... gives this output.
----------------------------------------------------------
Options:
  --help                a long help msg a long help msg a long help msg a
long
                        help msg a long help msg a long help msg a long
help
                        msg a long help msg
  --well_formated       As you can see this is a very well formatted option
                        description.
                        You can do this for example:

                        Values:
                          Value1: does this and that
                          Value2: does something else
                          Value3: has a very long
                                  description.
----------------------------------------------------------