[boost] Re: Re: Re: [program_options] multi-line description patch

From: Bertolt Mildner (Bertolt.Mildner_at_[hidden])
Date: 2005-01-17 05:54:29

> > > 2. I don't think that passing line width as construct parameter to
> > > options_descripton is optimal. It's not really property of options
> > > description. A better design would be do only line_width parameter to
the
> > > options_description::print method. What do you think?
> >
> > But this would mean no more oprator<< for options_descripton!
> > Not a real problem but existing code like
> >
> > os << desc;
> >
> > would have to be changed to
> >
> > desc.print(os, line_length);
> >
> > If you want i can make that change but the question is do you really
want
> > to?
> > (Assuming a default line_length for oprator<< does not really look
right to
> > me.)
>
> I think default line length will work for a large percentage of users,
and to
> make output with non-default line_length convenient we can introduce a
new
> function:
>
>   os << line_length(desc, 40)
>
> which will create a special object that will call 'print' with the right
> parameters.
>
> What do you think?

OK OK, i think i will we able to live with it :)

> Regardless of what we decide on the above, your patch is almost finished,
so
> I've just committed it. Thanks for the work and your patience!

You are welcome!

> > > 3. Do you plan to add detailed formatting description. If you don't
have
> >
> > the
> >
> > > time now, no problem, I'll commit the patch anyway.
> >
> > I plan to do. But probably not before new year.
>
> No pressure, but still would be nice ;-)

I'm not sure if i can descibe it in my own language in a way someone will
undestand it :(
anyway here is a first try:

-------------------------------
As the class options_description can be used to generate a help message
that can be presented to a user it is important to have some control over
the
formatting of the descrption of an option.

A description has one or more paragraphs.

Paragraphs are seperated by a explicit newline ('\n') and may be empty.
If a paragraph does not fit in one line it is spanned over multiple lines.
The library tries to prevent chopped words and leading spaces in new lines.
Words are chopped only if longer than half the available space. Leading
spaces are only skipped if not followed by a space.

A pragraph has two independend indent levels. One for the first line and
and one for the following lines if there are any.
The first line indent is done by simply inserting spaces at the beginning
of a pragraph.
The indent for following lines can be specified by inserting a tabulator
character ('\t') where the index of the tabulator is the indent length.
Before output the tabulator is removed. If the tabulator happens not to be
on the first line of the pragraph or is on the last possible position of
the first line it is ignored. Only one tabulator per paragraph is allowed
else an exception of type program_options::error is thrown.

This way of specifying indents may seem overly complicated but the
following examples hopefully demonstrate that usage is rather intuitive.

    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: \tdoes this and that, bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla\n"
                        "  Value2: \tdoes something else, bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla\n\n"
                        "    This paragraph has a first line indent only,
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla");

    std::cout << line_length(options, 50) << "\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, bla bla
                                  bla bla bla bla
                                  bla bla bla bla
                                  bla bla bla bla
                                  bla
                          Value2: does something
                                  else, bla bla
                                  bla bla bla bla
                                  bla bla bla bla
                                  bla bla bla bla
                                  bla

                            This paragraph has a
                        first line indent only,
                        bla bla bla bla bla bla
                        bla bla bla bla bla bla
                        bla bla bla

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

Hope that it makes some sense what i wrote!?

There should be better examples, just used the ones i already had.

Bertolt

PS: did you get my mail with the value_semantic patch?