Re: [Boost-docs] Quickbook blocks for concepts

Subject: Re: [Boost-docs] Quickbook blocks for concepts
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2010-02-09 11:00:46

Daniel James wrote:
> On 7 February 2010 18:42, Mateusz Loskot <mateusz_at_[hidden]> wrote:
>> There are some predefined blocks in Quickbook, like variablelist. 
>> I'm wondering if it would be beneficial to define a block dedicated
>>  for documenting concepts.
> 
> I'm unlikely to find the time to work on anything like that.
> Quickbook currently doesn't have any built support for normal
> reference documentation, let alone concepts.

I see. I asked if this idea would make any sense at all because
I've been thinking about *trying* to hack quickbook myself.

> There is some support for concepts in boostbook, if you look in the
> 'tools/boostbook/xsl/caramel' directory, although it doesn't seem to
> be documented and I haven't got any idea how it works. It might be
> best to ignore it.

Understood.

> Documenting concepts is difficult, as they're a bit abstract and 
> slippery. My advice would be to just look at documentation you've 
> found helpful and follow its lead.

Yes, that's right and that's what I'm doing, lurking, reading
and learning how to do it well.

> What you've written so far looks very good to me, better than a lot
> of our documentation.

It is very good to know, really.

> Sorry I'm not more helpful, maybe someone else has some better ideas?

You are helpful, thanks!

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net