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

Subject: Re: [Boost-docs] [quickbook] Does import work?
From: Daniel James (dnljms_at_[hidden])
Date: 2011-10-17 20:35:55

On 16 October 2011 20:09, Rene Rivera <grafikrobot_at_[hidden]> wrote:
> On 10/16/2011 11:38 AM, Daniel James wrote:
>>
>> 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?

Yes. The existing facility extracts snippets of code for inclusion in
a quickbook document - so it's still quickbook driven. The C++ files
are normally examples that are part of the documentation. You want C++
driven documentation which is something else - especially for C++
files that are part of the implementation.

>> 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.

Then write it in C++, which would be more maintainable than doing it
in quickbook (actually writing it in python would be as well).

Consider adding glob support to quickbook. First it will need to
integrate with quickbook's path system. An external tool wouldn't have
to do that. And whichever way you do it is going to be a bit fragile
since it'll be easy to accidentally pick up files. Then when it's
enshrined as a feature, someone will want to do a more sophisticated
glob, they'll want to control the order or exclude certain files, or
who knows what else.

If you look at the way quickbook parses C++ files to get the snippets,
the parser just looks for specially marked up comments and generates
templates from them which are only parsed as quickbook on expansion.
It isn't hard to do something like that in an external tool.

And quickbook is already complex enough. There's plenty that needs
fixing already. Adding features that should be implemented elsewhere
will just make things worse.

>> 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.

I meant it's messy to use special comments to ignore that parts you
don't want to appear, e.g. '//<-' and '//->' pairs. You'll also find
that if you want to define code snippets but not have them appear
inline it'll run into difficulties. Implementation files tend to be
messy, much of the doxygen documentation has preprocessor directives
for controlling what doxygen sees vs. what the compile sees, doing
something similar for quickbook would either involve making the
headers messier or making quickbook more complex.

> Also note, I'm not
> talking about needing this for a handful of files.. I'm dealing with
> documenting dozens of individual files.

That sounds like a good reason to use something with good file
handling capabilities.