Re: [Boost-docs] [quickbook] Phrase templates containing blocks

Subject: Re: [Boost-docs] [quickbook] Phrase templates containing blocks
From: Daniel James (daniel_at_[hidden])
Date: 2013-06-23 15:08:11

On 23 June 2013 15:53, Paul A. Bristow <pbristow_at_[hidden]> wrote:
>
>
>> -----Original Message-----
>> From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Daniel James
>> Sent: Sunday, June 23, 2013 10:24 AM
>> To: Discussion of Boost Documentation
>> Subject: [Boost-docs] [quickbook] Phrase templates containing blocks
>>
>> Hi,
>>
>> I've recently done a little on changing the way phrase and block templates work for 1.7. My
> initial
>> version (not in subversion yet) works by just changing the parser to allow blocks in phrase
> templates, and
>> letting the block handling code deal with it. This works okay, but can be surprising. For example
> this:
>>
>>     [template thing[] Text before table. [table]. Text after table.]
>>
>>     Text before template. [thing] Text after template.
>>
>> Generates:
>>
>>     Text before template.
>>
>>     Text before table.
>>
>>     [table]
>>
>>     Text after table.
>>
>>     Text after template.
>>
>> But I imagine most people would expect:
>>
>>     Text before template. Text before table.
>>
>>     [table]
>>
>>     Text after table. Text after template.
>
>> Does that look right to you?
>
> If I've understood this right, I suppose so, but I think people can cope with either, but it's
> better to have an 'extra newline' than being tempted (forced?) into using an explicit forbidden
> newline.

I'm not sure what you mean as "an explicit forbidden newline".

Maybe I should explain my reasoning a bit better. Phrase templates
normally just do something like text substitution, i.e. in this case:

    Text before template. Text before table. [table] Text after table.
Text after template.

But `[table]` is a block element, so that is equivalent to:

    Text before template. Text before table.

    [table]

    Text after table. Text after template.

>> It'll need some changes to implement that, but it's doable. The problem is,
>> what should happen in a case like this:
>>
>>     [template thing1[] Line 1
>>
>>     Line 2]
>>
>>     Text before template. [thing1] Text after template.
>>
>> What do you think that should that be? (Don't think about what it currently does).
>
> My brain hurts!  I just wants this control-of-newlines problem to go away ;-)

Then maybe this should be an error? Something like, "Paragraph break
in phrase template". It's certainly an odd thing to write. Would
anyone who isn't trying to devise convoluted edges cases ever write
it?