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

From: Julio M. Merino Vidal (jmmv84_at_[hidden])
Date: 2006-08-03 04:50:35

On 8/3/06, Joel de Guzman <joel_at_[hidden]> wrote:
> 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?

Not that I know of.  However, it might still be useful to be able to
explicitly specify the format in case someone uses custom extensions.
It'd be automatically guessed based on the extension and be left
optional.  (E.g. you might have a '.docbook' file instead of a '.xml'
one; I think I've seen that somewhere...)

But my point was about the following.  At the moment, include syntax is one of:

    [include file.qbk]
    [include:some-id file.qbk]

If the command is changed to be general such as:

    [include<:id> <file> <format> <section>]

The new syntax could allow the following incorrect constructions:

    [include file.xml xml some-section]

        As XML files are included with a specific tag, the parser cannot
        do anything about the section.  So the user could get unexpected
        results if he gave a section name.

    [include:some-id file.cpp]

        The some-id has a meaning when including Quickbook documents,
        but not source code.

Anyway, this is not such a big problem.  Quickbook could detect such
incorrect cases and raise an error so that the user could correct his
code.

Cheers,

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