Re: [boost] [quickbook] template vs block vs phrase issues

Subject: Re: [boost] [quickbook] template vs block vs phrase issues
From: Daniel James (dnljms_at_[hidden])
Date: 2012-12-07 12:18:06

On 6 December 2012 13:45, Andreas Pokorny <andreas.pokorny_at_[hidden]> wrote:
> Hi,
> I use quickbook to write software design documentation targeting pdf.
> We now introduce a requirements tracking system that includes both
> source code and design documents. To describe or refer to requirements
> in docbook docments special xml markup is needed. I.e. something like
> <reqfooo><status>approved</status><version>1</version><id>DoOnlyNeededStuff</id><description></description></regfoo>.
> Since I do not want to write XML I added quickbook templates:
>
> [template reqfoo[id
> contents]'''<reqcfoo><id>'''[id]'''</id>'''[contents]'''</reqfoo>''']
> [template sdesc[contents]'''<shortdesc>'''[contents]'''</shortdesc>''']
> [template verification[contents]'''<verifycrit>'''[contents]'''</verifycrit>''']
> [template source[contents]'''<source>'''[contents]'''</source>''']
> [template usecase[contents]'''<usecase>'''[contents]'''</usecase>''']
> [template status[contents]'''<status>'''[contents]'''</status>''']
> [template version[contents]'''<version>'''[contents]'''</version>''']
>
> and finally:
> [template desc[contents]'''<description>'''[contents] '''</description>''']
>
> Now I want to use block elements inside the contents parameter of
> desc. Is there any way to achieve that? The only thing I can think of
> is:
>
> [template desc[]'''<description>''']
> [template enddesc[]'''</description>''']
>
> But then quickbook is just as good as xml!
>
> I tried to make desc a block level template by adding a line break at
> different positions, but then I get broken xml code, since para tags
> are spread around <description>

I don't think you can with the current quickbook. I started trying to
fix this, but never finished it. The following sort of works (by using
'quickbook 1.6' the document opts into the extra experimental features
that I added, but I'm not sure if they'll ever be made final).

It uses a horrible hack to pass block markup to the template. The
problem is that the parser swallows up any whitespace between a
template call and its first argument (including newlines), so that the
first argument can't be block markup. But the second can if the call
uses the '..' separator, so that's why it uses 'x..', 'x' is the first
parameter that's ignored. Shouldn't be too hard to implement something
better for 1.6.

In 'desc' I use the 'block' tag, which is a 1.6 tag that says its
contents should be considered block markup and shouldn't be used
inside paragraph tags. The name is a bit confusing - it doesn't mean
that the contents are quickbook blocks, something like 'not-a-phrase'
might be better.

[article Blah
[quickbook 1.6]
]

[template desc[x1 x2]
[block '''<description>''']
[x2]
[block '''</description>''']
]

[desc x..
Paragraph 1

Paragraph 2
]