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

From: Vladimir Prus (ghost_at_[hidden])
Date: 2004-12-07 02:45:57

Hi Bertolt,

>> 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.

So, the position of tab basically sets a indent level for the remaining
lines in the paragraph. Now I understand this. However, I don't like the
"last tab takes effect" rule. What if that last tab is on the third line of
the paragraph? Maybe, it's clearer (in code and in docs) to allow only one
tab in a paragraph and throw otherwise? Or do you have a use case for
multiple tabs?

>   (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.

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

Yea, I understand now.

>> 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.

Thanks, I understand the situation now. I think loosing 1 character is not a
big problem, so introducing two modes is not necessary.

>> 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.

Ok. I guess if "slice = min<....>" were at the top of the loop, I would not
be confused by this code -- I though you have to do clipping anyway, not
only when there's leading whitespace. 

BTW, maybe, you can put "slice = " code after "if (!first_line) and remove
the clipping inside that "if"?

> 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?

Sorry, the comment there is OK:

šššš//šifš(lastcharš!=š'š')š&&
šššš//šššš(exists(lastcharš+š1)š&&š(lastcharš+š1š!=š'š')

I misparsed it as old code you've commented out, not as real comment ;-)

>> 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.

Thanks you! I'm looking forward.

- Volodya