Re: [Boost-docs] [quickbook] Does import work?

Subject: Re: [Boost-docs] [quickbook] Does import work?
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2011-10-16 19:09:05

On 10/16/2011 11:38 AM, Daniel James wrote:
> On Sunday, 16 October 2011, Rene Rivera wrote:
>>
>>
>> Right. I'm trying to have "[import ..]" work as easy as Doxygen does, but
>> for quickbook. As documenting the library I'm working on would otherwise be
>> a serious PITA. And I'd rather avoid using Doxygen for it as it's much
>> easier to deal with quickbook directly. Ultimately I want to be able to:
>>
>> ===
>> [import boost/predef/*.h]
>> [import boost/predef/*/*.h]
>> [import boost/predef/*/*/*.h]
>> ===
>>
>> And have all the documentation that's embedded in those source files
>> injected into the quickbook stream. Without me having to maintain what the
>> files are, or what they contain.
>>
>
> So you don't want to include the whole headers, just the documentation
> embedded in them?

Right.

> This feels like a bit of an odd thing to do in quickbook
> itself,

Is it any odder than the existing import facility?

> I'd probably write a script to extract the documentation first and
> then include the extracted documentation from quickbook.

That sounds much less maintainable than either extending quickbook or 
manipulating Doxygen to give the results I want. Especially given that 
I'd have to then deal with writing multiple scripts, sh/BAT, or use Python.

> I suppose you could use special comments to strip out the parts you don't
> want to appear, but I expect it'd get messy.

Is it any messier than the existing import facility? Note, IMO it's not 
only not messier than the existing import, it's actually less messy. 
Since there's less likelihood of making a mistake when I don't have to 
essentially duplicate template names on both sets of files (source and 
qbk). And there's less superfluous stuff I have to put in the source 
files. Also note, I'm not talking about needing this for a handful of 
files.. I'm dealing with documenting dozens of individual files.

-- 
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org (msn) - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim,yahoo,skype,efnet,gmail