Re: [boost] [quickbook] Including source files in the document

From: Joel de Guzman (joel_at_[hidden])
Date: 2006-08-03 00:54:47

Julio M. Merino Vidal wrote:
> On 8/1/06, Joel de Guzman <joel_at_[hidden]> wrote:
>> Giovanni Piero Deretta wrote:
>>
>>>> Anyway, as Eric said it may be better to make [include] more
>>>> intelligent.  What about making it take two arguments, one specifying
>>>> the file name and the other the format?  E.g.
>>>>
>>>> [include somefile.xml xml]
>>>> [include code.cpp c++]
>>>> [include foo.qbk quickbook]
>>>
>>> What about including only *part* of a file?
>>> i.e. marking a file with with comments with something like
>>>
>>>
>>> --- in file source.cpp ---
>>> ...
>>> //  quickbook:begin("section name")
>>> ...
>>> // quickbook:end("section name")
>>> ...
>>> --------
>>>
>>> [include source.cpp C++ "section name"]
>>> would include only that part of the file.
>>>
>>> Useful if you want to pull for example only a function prototype, or a
>>> single
>>> class declaration...
>> Yes. These are what I had in mind when I asked Julio if he's
>> interested to do more coding. Eric and Giovanni summed it all
>> up. There was something like this before but it got out of
>> sync with the code and got lost. I do not even recall now
>> who wrote it.
> 
> As I'm working on this, I find some problems when trying to unify it
> all in a single "include" keyword.  I.e., trying to support something
> like:
> 
> [include file.qbk quickbook some-section]
> [include file.xml xml some-section]
> 
> When including a quickbook file, the program redefines __FILENAME__
> and also lets the caller define a file identifier for the included
> contents.  I guess this is only applicable to this format.
> 
> Similarly including a XML file does not place a verbatim copy into the
> resulting file.  Instead, quickbook generates a <xi:include> tag to
> refer to the external file.  In this case, the "only include part of
> the file" suggestion is not applicable (unless we change the sematincs
> and just duplicate the included xml file into the resulting code; not
> too "problematic").
> 
> These inconsistencies could become special cases for the generic
> include tag, meaning that depending on the file format, it'd behave
> differently.  I'm not so sure this is good.
> 
> Alternatively we'd simply have a new tag (dunno how to call it)
> targetted to other file formats.  This could allow the features
> requested but not allow inclusion of quickbook and xml files.  E.g.
> 
> [still_without_name_include file.cpp c++ main-function]
> 
> But then... there are three different tags to include files, each one
> with its own behavior and purpose.
> 
> Any suggestion on how to proceed?

Is dispatching against the file extension really such a bad idea?
AFAICT, we only have 1) qbk 2) xml and 3) anything else regarded
as code include. So why not simply generalize it to:

[include file.qbk]
[include file.xml]
[include file.hpp optional_some_section]

Am I missing some potential problems and gotchas?

Regards,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net