[Boost-docs] Quickbook block element

Subject: [Boost-docs] Quickbook block element
From: Daniel James (dnljms_at_[hidden])
Date: 2011-10-21 12:32:36

Hi,

This is something I've implemented but not checked in yet which is a
little relevant to recent discussions. Currently when you might try to
write something like this:

    [template chapter[title] '''<chapter><title>'''[title]'''</title>''']
    [template chapterend '''</chapter>''']

    [chapter Just an example]

    Chapter content.

    [chapterend]

It doesn't work because escaped docbook is considered to be a phrase
element. Phrase elements are wrapped in a paragraph resulting in
invalid xml such as:

<para>
  <chapter><title>Just an example</title>
</para>
<para>
  Chapter content.
</para>
<para>
  </chapter>
</para>

So I've added a 'block' element which has phrase content (i.e. no
paragraphs, lists etc.) but treats it as a block. This allows:

    [template chapter[title] [block'''<chapter><title>'''[title]'''</title>''']]
    [template chapterend [block'''</chapter>''']]

And that works (as long as you always correctly match up 'chapter' and
'chapterend'). It's a bit of a hack, I'm not sure how understandable
it is to someone who doesn't know quickbook's internals. There also
might need to a converse tag to cleanly include blocks inside a phrase
(innerblock?). Any better ideas? I thought about creating different
types of templates although that's something I'd like to leave alone
for now.

Another possibility is to parse the escaped xml and try to work it
out, but that seems a little fragile, maybe possible if quickbook
generated a whole AST. But it would also make it trickier to add new
targets to quickbook.