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

Subject: Re: [Boost-docs] [quickbook] Does import work?
From: Vicente J. Botet Escriba (vicente.botet_at_[hidden])
Date: 2011-10-19 06:16:12

Le 19/10/11 06:02, Rene Rivera a écrit :
> On 10/18/2011 1:18 PM, Daniel James wrote:
>>> What you want has two phases - the first phase is to gather the
>>> documentation source out of the headers, the second is the
>>> documentation generation phase. These are quite distinct. There's no
>>> good reason to squash them together. That's not a "bad excuse", that's
>>> separation of concerns.
>> It seems that your sentiment runs counter to the Literate Programming
>> ideals. Or maybe I don't understand the two parts you are referring to.
>>> You don't need an excuse to reject a feature, you need a reason to
>>> add it.
>> OK, good point. And I think I already stated my reasons for adding
>> it. Which as Dave pointed out fall within the Literate Programming
>> ideals.
Hi all,

IMO, Rene you are right, it is a good idea to include the quickbook
comments associated to the documentation of a C++ file.

But as Daniel has already said you can already do that by extracting the
comments yourself. Note that I'm not saying that I don't want quickbook
to integrate these features.

Doing that 'by hand' for a library documentation would increase the
experience of what exactly is needed to integrate it in quickbook.

For the needs you have expressed, it seems that it is enough to tag the
begin-end of the C++ comments you want to extract. Following the import
syntax, we could use

// [quickbook-comments

// ] quickbook-comments

The we could cat all the C++ files from which you want to extract the
quickbook comments and give this file to a simple quickbook extractor
command. Do we have a cat utility integrated in Boost.Build?

cat boost/predef.hpp boost/predef/*.hpp boost/predef/*/*.hpp |
quickbook-extractor > predef-extracted.qbk

All you need is to include the resulting file.

[include predef-extracted.qbk]

 From my side having the ability to import files with '*' characters is
not a critical feature for quickbook as I have always preferred to
include the files explicitly. Why? Two reasons: First because I want to
master the order of the documentation associated to a file and second
because I want to be able to document any file, even implementation
files, and I don't want the build chain include automatically these
comments into the user documentation. This facility could be useful when
you want to provide a documentation of the internals of a library.

Of course, we could use different tags for public and internals comments

// [quickbook-public-comments
// ] quickbook-public-comments

// [quickbook-detail-comments
// ] quickbook-detail-comments

I'm sure that the experience will show that we want to split the
documentation associated to a C++ file, at least in tutorial and
reference, so we will need more tags to differentiate them:

// [quickbook-public-comments:tutorial
// ] quickbook-public-comments:tutorial

// [quickbook-public-comments:reference
// ] quickbook-public-comments:reference

With these tags, the extraction of the tutorial and reference sections
could be done like

cat boost/predef.hpp boost/predef/*.hpp boost/predef/*/*.hpp |
quickbook-extractor --section tutorial > predef-tutorial-extracted.qbk
cat boost/predef.hpp boost/predef/*.hpp boost/predef/*/*.hpp |
quickbook-extractor --section reference > predef-reference-extracted.qbk

Once we have see the extent of the approach, maybe Daniel could include
the feature in quickbook and why not provide a quickbook command as for

[section Tutorial
[include-extracted boost/predef.hpp tutorial]

[section Reference
[include-extracted boost/predef.hpp reference]

One of the advantage of integrating it in quickbook is to simplify the
Build process, the other is that the errors could report the source file
line number and not the one of a temporary file.

I'm sure, other will find different ways of implementing this
interesting approach.

Well this is just how I see the path to improve the integration of Boost
documentation and Boost code.

Thanks Rene for raising this excellent idea,

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC