[BBv2] quickbook.jam and boostbook questions

From: Joao Abecasis (jpabecasis_at_[hidden])
Date: 2005-01-08 14:24:09

Hi all!

The attached jam toolset defines a rule for the generation of Boost.Book 
documentation from QuickBook sources.

For those not familiar with QuickBook,

[ from the docs ]
« QuickBook is a WikiWiki style documentation tool geared towards
C++ documentation using simple rules and markup for simple
formatting tasks. Like the WikiWiki, QuickBook documents are
simple text files. »

You may find QuickBook on Spirit's CVS (http://tinyurl.com/6ckpz) or 
under xpressive on Boost-Sandbox (http://tinyurl.com/682an).

The toolset allows a user to set the location of the quickbook excutable 
and defines a QUICKBOOK to BOOSTBOOK generator. boostbook.boostbook is 
aliased to quickbook.quickbook for convenience. This alias is supposed 
to impose the requirement that the quickbook toolset be initialized, 
although it's really just an alias...

I would like to propose the addition of the file under BBv2/tools/, but 
I still have a couple of questions for you (even if ultimately you don't 
want to add it there ;).

1. boostbook.jam defines the BOOSTBOOK type. However, it's generators 
are defined as XML -> <something>. Given this I found 2 ways to make 
quickbook work:
a) define generator QUICKBOOK -> XML, which leaves me with the
feeling that the generator is not sufficiently "typed"...

b) define generators BOOSTBOOK -> DOCBOOK (and BOOSTBOOK -> TESTS)
and QUICKBOOK -> BOOSTBOOK. This seems better, but I shouldn't
be messing with boostbook within the quickbook toolset.

Are there other alternatives I am missing? How bad could it be to define 
the generator as QUICKBOOK -> XML?

2. Currently I rely on the user providing the quickbook command in 
site-config.jam or user-config.jam with

using quickbook : path/to/quickbook ;

I haven't looked it up yet, but I guess I could have the executable 
generated on the fly. However, I wouldn't want to force quickbook 
compilation with different compilers, just to get docs generated.

Is there a way to mark quickbook for compilation by a "default" or a 
single compiler and always use that?

Is it a good idea to have the quickbook executable built on-the-fly, or 
should I rely on the user explicitly setting it up?

Are there other toolsets where a similar issues arise? How are they 
handled there?

Thanks for your time,

Best regards,

João Abecasis
 --------------050705080307050100050706 Content-Type: text/plain;
name="quickbook.jam"
Content-Transfer-Encoding: base64
Content-Disposition: inline;
filename="quickbook.jam"

IwojIENvcHlyaWdodCAoYykgMjAwNSBKb2FvIEFiZWNhc2lzCiMKIyBEaXN0cmlidXRlZCB1
bmRlciB0aGUgQm9vc3QgU29mdHdhcmUgTGljZW5zZSwgVmVyc2lvbiAxLjAuIChTZWUKIyBh
Y2NvbXBhbnlpbmcgZmlsZSBMSUNFTlNFXzFfMC50eHQgb3IgY29weSBhdAojIGh0dHA6Ly93
d3cuYm9vc3Qub3JnL0xJQ0VOU0VfMV8wLnR4dCkKIwoKIyBQcm92aWRlcyBxdWlja2Jvb2sg
cnVsZSB0byBoYW5kbGUgZ2VuZXJhdGlvbiBvZiBkb2N1bWVudGF0aW9uIGZyb20gUXVpY2tC
b29rIFNvdXJjZXMuCiMgSW50ZXJlc3Rpbmcgc3R1ZmYgaXMgaW4gYm9vc3Rib29rLi4uCgpp
bXBvcnQgYm9vc3Rib29rIDsKaW1wb3J0IGNvbW1vbiA7CmltcG9ydCBnZW5lcmF0b3JzIDsK
aW1wb3J0IG1vZHVsZXMgOwppbXBvcnQgdHlwZSA7Cgp0eXBlLnJlZ2lzdGVyIFFVSUNLQk9P
SyA6IHFiayA7CgpydWxlIGluaXQgKCBjb21tYW5kID8gKQp7CiAgICBpZiAhICQoLmluaXRp
YWxpemVkKQogICAgewogICAgICAgIC5pbml0aWFsaXplZCA9IHRydWUgOwoKICAgICAgICAu
cXVpY2tib29rLWNvbW1hbmQgPSBbIGNvbW1vbi5nZXQtaW52b2NhdGlvbi1jb21tYW5kIHF1
aWNrYm9vayA6IHF1aWNrYm9vayA6ICQoY29tbWFuZCkgXSA7CgogICAgICAgIGlmIC0tZGVi
dWctY29uZmlndXJhdGlvbiBpbiBbIG1vZHVsZXMucGVlayA6IEFSR1YgXSAKICAgICAgICB7
CiAgICAgICAgICAgIEVDSE8gIm5vdGljZTogUXVpY2tCb29rOiB1c2luZyBjb21tYW5kICIg
JCgucXVpY2tib29rLWNvbW1hbmQpIDsKICAgICAgICB9CgogICAgICAgICMgVGhlc2UgZ2Vu
ZXJhdG9ycyBzaG91bGQgbm90IGJlIGhlcmUuLi4gTXVzdCBtYWlsIHRoZSBCQiBndXlzIGFu
ZCBhc2sKICAgICAgICAjIGZvciBhZHZpY2Ugb3IgZ28gdGhlIChvdGhlcikgZWFzeSB3YXkg
b3V0IGJ5IGRlZmluaW5nIFFVSUNLQk9PSyB0byBYTUwKICAgICAgICAjIGdlbmVyYXRvciwg
YmVsb3cuCiAgICAgICAgZ2VuZXJhdG9ycy5yZWdpc3Rlci1zdGFuZGFyZCBib29zdGJvb2su
Ym9vc3Rib29rLXRvLWRvY2Jvb2sgOiBCT09TVEJPT0sgOiBET0NCT09LIDsKICAgICAgICBn
ZW5lcmF0b3JzLnJlZ2lzdGVyLXN0YW5kYXJkIGJvb3N0Ym9vay5ib29zdGJvb2stdG8tdGVz
dHMgOiBCT09TVEJPT0sgOiBURVNUUyA7CgogICAgICAgICMgUmVnaXN0ZXJpbmcgdGhlIGdl
bmVyYXRvciBoZXJlIHJlcXVpcmVzICd1c2luZyBxdWlja2Jvb2sgOycgc29tZXdoZXJlIGVs
c2UKICAgICAgICBnZW5lcmF0b3JzLnJlZ2lzdGVyLXN0YW5kYXJkIHF1aWNrYm9vay5xdWlj
a2Jvb2stdG8tYm9vc3Rib29rIDogUVVJQ0tCT09LIDogQk9PU1RCT09LIDsKCiAgICAgICAg
IyBNYWtlIGJvb3N0Ym9vayBydWxlIHZpc2libGUgYXMgcXVpY2tib29rLnF1aWNrYm9vawog
ICAgICAgIElNUE9SVCBib29zdGJvb2sgOiBib29zdGJvb2sgOiAkKF9fbmFtZV9fKSA6IHF1
aWNrYm9vayA7CiAgICAgICAgIyBBbmQgdGhlbiBhcyBnbG9iYWwgcXVpY2tib29rCiAgICAg
ICAgSU1QT1JUICQoX19uYW1lX18pIDogcXVpY2tib29rIDogOiBxdWlja2Jvb2sgOwogICAg
fQp9CgojICQoMSkgdGFyZ2V0CiMgJCgyKSBzb3VyY2UKYWN0aW9ucyBxdWlja2Jvb2stdG8t
Ym9vc3Rib29rCnsKICAgICQoLnF1aWNrYm9vay1jb21tYW5kKSAkKDIpICQoMSkgOwp9Cgo=
 --------------050705080307050100050706--