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

From: Bertolt Mildner (Bertolt.Mildner_at_[hidden])
Date: 2004-12-06 14:44:59

"Vladimir Prus" <ghost_at_[hidden]> schrieb im Newsbeitrag
news:cp13no$2cr$1_at_sea.gmane.org...

> Basically, the change is great but I'd like to clarify some things.
>
> 1. You wrote:
> > - The indent is set as the position of the last tab ('\t') in a
paragraph,
> > other tabs are ignored.
>
> Could you clarify this? I could not understand this from the example
you've
> given.

I can try, but don't know if i can get it much clearer than my example ...

My intentions behind this feature are:
- If tabs are outputted as tabs they may easily destroy the formatting.

- It would be nice to indent a paragraph relative to first_column_width.

So paragraph formatting works the following way:
- All tabs are removed before output.

- If the first line of a paragraph should be indented this has to be done
  with one or more spaces. (There is no trimming done in the first line!)

- If a paragraph is spanned across multible lines, following lines are
  indented (relative to first_column_width) using the position of the last
  tab in the paragrapth.
  (Please note that other tabs are not adding to the position of the last
one!)

So a paragrapth as two indentation levels (relative to first_column_width).
A "first line indent" and a indent for succeeding lines, if there are any.

OK, this sounds very complex but it isn't in practical usage.

Some examples for pragraph formatting:

"bla bla bla bla bla bla bla bla bla bla"

bla bla bla bla
bla bla bla bla
bla bla

"    bla bla bla bla bla bla bla bla bla bla"

    bla bla bla
bla bla bla bla
bla bla bla

"    \tbla bla bla bla bla bla bla bla bla bla"

    bla bla bla
    bla bla bla
    bla bla bla
    bla

> 2. I'd prefer that your code be a separate function, which takes a string
> and outputs it (or returns a new string with proper line-breaks/indents).

OK, should be easy.

> 3. Such a function really should have comments. It's very hard to
understand
> the exact formatting rules from the code, and such documentation must be
> present in some form. If you'll provide code comments, I'll eventually
> update the documentation. You can just copy all the explanations you've
> given in your email to the comment and review it for clarity.

OK, i'll try to improve on that.

> 4.
>
>  // we need to use one char less per line to work correctly if actual
>  // console has longer lines
>
> Could you clarify?

At last in Win32 consoles the cursor gets moved to a new line after writing
to the
last possible location in a line.

So you basically have two options:
- Use full console lines *but* smasch fromatting if console happens to have
longer lines.

- Use "manual newlines", so sacrifice one char for the '\n' *but*
formatting is intact in
  larger consoles.

That is why I wrote in a previous post that may be two modes would be nice:
- One where the *exact* line length is known.
- One where line_length is just a guess, and formatting works in consoles
with *at last*
  line_length long lines.

> 5.
>
>    // trimm slice if out of bounds
>    if (i + slice > e)
>    {
>       slice -= 1;
>    }
>
> Why do you do this?

The current part (= line) of a paragraph is [i, i + slice].
So if i is increased "i + slice" may move beond the end of the paragraph.

BTW: there might be a problem if slice gets 0, have to look into that

> 6.
>    // prevent chopped words
>    if ((*(i + (slice - 1)) != ' ') &&
>       (((i + slice) < e) && (*(i + slice) != ' ')))
>
> This really needs a more verbose comment. Like 'check if current line
ends
> in non-space, and the next character is non-space too'.

More verbrose that the comment in my last patch?

> 7.
>    slice = min<string::difference_type>(line_length - indent, e - i);
>
> Maybe, this should be moved to the top of the loop. I was confused by the
> assignment which is not used below.

Yes, i think you are right.

> 8. This is completely up to you, but I wonder if consistently using
string
> indices everywhere would be clearer. Now you use both indices and
iterators
> and need to convert between them.

I absolutely agree with you!
I'm not at all happy with the current implementation my self.
So it's on my todo list, too.

Thank you very much for your comments!

Stay tuned for a new patch.

Bertolt