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 
example

[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,
Vicente