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

From: Julio M. Merino Vidal (jmmv84_at_[hidden])
Date: 2006-08-02 08:39:10

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?

-- 
Julio M. Merino Vidal <jmmv84_at_[hidden]>
The Julipedia - http://julipedia.blogspot.com/