[quickbook] Including source files in the document
Hi, I've just started adding example programs to my SoC project and I was wondering if there was a way to bundle their code into the documentation (which I'm writing with Quickbook). Of course I can hyperlink to the source file, but this could be useless in printed documentation. Also I'd copy&paste the C++ code in the qbk file, but that is asking for trouble (desyncronization). Hence, I think it'd be useful to be able to include this code in the final document straight from the qbk file. I tried with the [include ...] command but it did not work as I expected. And indenting it in the .qbk file so that it was formatted as source code made things worse because the inclusion had no effect at all. Similarly, [xinclude ...] cannot work either for obvious reasons (source code is not XML). So... I added a 'cinclude' tag (standing for code include) to quickbook which, given a file, includes it in the documentation marked up (and colored!) appropriately. The implementation is attached. It can very well be flawed as it is basically a copy&paste of other parts of the code, but so far seems to work. Any chance this -- or something similar -- can be integrated? Thanks. -- Julio M. Merino Vidal <jmmv84@gmail.com> The Julipedia - http://julipedia.blogspot.com/
Julio M. Merino Vidal wrote:
Hi,
I've just started adding example programs to my SoC project and I was wondering if there was a way to bundle their code into the documentation (which I'm writing with Quickbook). Of course I can hyperlink to the source file, but this could be useless in printed documentation. Also I'd copy&paste the C++ code in the qbk file, but that is asking for trouble (desyncronization). Hence, I think it'd be useful to be able to include this code in the final document straight from the qbk file.
I tried with the [include ...] command but it did not work as I expected. And indenting it in the .qbk file so that it was formatted as source code made things worse because the inclusion had no effect at all. Similarly, [xinclude ...] cannot work either for obvious reasons (source code is not XML).
So... I added a 'cinclude' tag (standing for code include) to quickbook which, given a file, includes it in the documentation marked up (and colored!) appropriately. The implementation is attached. It can very well be flawed as it is basically a copy&paste of other parts of the code, but so far seems to work.
Any chance this -- or something similar -- can be integrated?
Certainly. I might need to ask for some more cinclude related features. Are you willing to do some more coding? Please email me. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
On Tue, 01 Aug 2006 22:28:19 +0800, Joel de Guzman <joel@boost-consulting.com> wrote:
Any chance this -- or something similar -- can be integrated?
Certainly. I might need to ask for some more cinclude related features. Are you willing to do some more coding? Please email me.
May I ask to rename it to something comprising "code", rather than 'c'? The term "cinclude" makes me think of <cmath>, <cstddef> and the like; "code_include" or "include_code" would just make me happier. As you see, I'm content with little O:) -- [ Gennaro Prota, C++ developer for hire ]
Joel de Guzman wrote:
So... I added a 'cinclude' tag (standing for code include) to quickbook which, given a file, includes it in the documentation marked up (and colored!) appropriately. The implementation is attached. It can very well be flawed as it is basically a copy&paste of other parts of the code, but so far seems to work.
Any chance this -- or something similar -- can be integrated?
Certainly. I might need to ask for some more cinclude related features. Are you willing to do some more coding? Please email me.
Just a thought, but would it be better to make [include ] a phrase level element so it can include code or whatever, otherwise we'll end up with [cinclude ] and [pyinclude ] and [terminal_include ] and...... etc. John.
John Maddock wrote:
Joel de Guzman wrote:
So... I added a 'cinclude' tag (standing for code include) to quickbook which, given a file, includes it in the documentation marked up (and colored!) appropriately. The implementation is attached. It can very well be flawed as it is basically a copy&paste of other parts of the code, but so far seems to work.
Any chance this -- or something similar -- can be integrated? Certainly. I might need to ask for some more cinclude related features. Are you willing to do some more coding? Please email me.
Just a thought, but would it be better to make [include ] a phrase level element so it can include code or whatever, otherwise we'll end up with [cinclude ] and [pyinclude ] and [terminal_include ] and...... etc.
Phrases cannot include block-level elements, so if you want to be able to [include] another .qbk file which contains blocks, [include] cannot be a phrase. I would favor making [include] smarter, perhaps checking the extension of the file and acting appropriately. -- Eric Niebler Boost Consulting www.boost-consulting.com
On 8/1/06, John Maddock <john@johnmaddock.co.uk> wrote:
Joel de Guzman wrote:
So... I added a 'cinclude' tag (standing for code include) to quickbook which, given a file, includes it in the documentation marked up (and colored!) appropriately. The implementation is attached. It can very well be flawed as it is basically a copy&paste of other parts of the code, but so far seems to work.
Any chance this -- or something similar -- can be integrated?
Certainly. I might need to ask for some more cinclude related features. Are you willing to do some more coding? Please email me.
Just a thought, but would it be better to make [include ] a phrase level element so it can include code or whatever, otherwise we'll end up with [cinclude ] and [pyinclude ] and [terminal_include ] and...... etc.
Note that cinclude stands for "code include", not "C include"; hence the pyinclude wouldn't exist ;-) 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] The first one could make xinclude deprecated and the last one could be made to avoid the 'quickbook' extra word to preserve the current syntax. -- Julio M. Merino Vidal <jmmv84@gmail.com> The Julipedia - http://julipedia.blogspot.com/
On 8/1/06, Julio M. Merino Vidal <jmmv84@gmail.com> wrote:
On 8/1/06, John Maddock <john@johnmaddock.co.uk> wrote:
Joel de Guzman wrote:
So... I added a 'cinclude' tag (standing for code include) to quickbook which, given a file, includes it in the documentation marked up (and colored!) appropriately. The implementation is attached. It can very well be flawed as it is basically a copy&paste of other parts of the code, but so far seems to work.
Any chance this -- or something similar -- can be integrated?
Certainly. I might need to ask for some more cinclude related features. Are you willing to do some more coding? Please email me.
Just a thought, but would it be better to make [include ] a phrase level element so it can include code or whatever, otherwise we'll end up with [cinclude ] and [pyinclude ] and [terminal_include ] and...... etc.
Note that cinclude stands for "code include", not "C include"; hence the pyinclude wouldn't exist ;-)
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... -- Giovanni P. Deretta
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. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
On 8/1/06, Joel de Guzman <joel@boost-consulting.com> 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@gmail.com> The Julipedia - http://julipedia.blogspot.com/
Julio M. Merino Vidal wrote:
On 8/1/06, Joel de Guzman <joel@boost-consulting.com> 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
On 8/3/06, Joel de Guzman <joel@boost-consulting.com> 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@gmail.com> The Julipedia - http://julipedia.blogspot.com/
Julio M. Merino Vidal wrote:
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.
Yes. That's an issue of syntax vs. semantics. The incorrect usage you noted clearly fall under semantics, hence, is not a concern of the parser proper. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Joel de Guzman wrote:
Any chance this -- or something similar -- can be integrated?
Certainly. I might need to ask for some more cinclude related features. Are you willing to do some more coding? Please email me.
How does this interact with the "literal programming" idea? I still very much want to see that implemented. Wish I had time to do it myself. -Dave
participants (7)
-
David Greene -
Eric Niebler -
Gennaro Prota -
Giovanni Piero Deretta -
Joel de Guzman -
John Maddock -
Julio M. Merino Vidal