Daniel James wrote:
2008/8/18 Dean Michael Berris <mikhailberis@gmail.com>:
Another option (that I think Dave Abrahams has been doing) is to use RST [0] to make writing/reading the source documentation easier than having to rely on Boostbook+XSLT (which I personally think is a brittle tool-chain).
We haven't a single problem with boostbook or xslt. It's actually quite stable. The problems have been with boost build, quickbook (possibly due to Spirit), doxygen and latex. Basically everything but boostbook. Most of the problems seem to involve poor support for windows. I've been testing on linux which is why they weren't discovered sooner.
I changed the subject to emphasize that my point isn't about boost book but rather boost tools. I picked boost book as an example in part because I didn't remember who was responsable for it. But this illustrates the heart of my proposal. Let suppose that the following tools each had its own test suite, library, review, etc. - the whole boost process. Here is what we would have boost/ /tools /bjam /boostbuild (depends upon bjam) /boostbook (depends upon fop, doxygen, docbook and ?) /quickbook (depends upon boostbook, and spirit) Now how would things look now? a) testing on windows would be done - it couldn't be avoided! b) "Getting Started: would look a lot different. toos/bjam would contain the documentation for bjam. and boostbuild would probably contain the rest of it. c) The bjam tests would not depend on all the *.jam files testing of boostbuild (all the *.jam) files would be run whenever bjam was recompiled c) boostbuild would be tested independently of quickbook. I know this would be helpful because I believe that docbook has evolved somewhat. d) quick book would be either tested independently or if that isn't possible, it would be tested if and only if boostbook tests passed. Actually, I know that lots of stuff is sprinkled around the directories already. So a lot of it would be just moving things around. Here are a number of other advantages a) I loaded my amended "Library Status" into the directory which contains "compiler status" because that was a logical place. Its looked good on my windows and gcc compilers but crashed the whole boost test process on certain compilers. Further, this tool wasn't subjected to any kind of boost review process. Is this a good idea? Application of the "boost process" would permit ideas for tools to be subjected to wider scrutiny and improve quality. b) As noted above, it would be alot easier to find the source of bugs. c) It would more clearly delineate responsability. That is the author of bjam wouldn't necessarily get sucked in to issues related to errors in the creation of Jamfiles - unless he want's to. d) Documentation would be more logical and easier to maintain. The "Getting Started" guide is an example. It's a heroic effort and quite well written. But by trying to cover bjam and boost build together, it's less clear than it could be. It's also much harder to maintain since it covers such a wide territory in the area of responsability of various persons. By factoring the boost toolset in smaller more orthogonal pieces, efforts such as the "Gettings Started Guide" would be more productive and more easily divided amongst several people. e) It would improve tool usability and range of application. There are two ways of looking at bjam. The first is "Key part of the boost build system". The second is "The next/great 'make'". I believe that it's currently thought of as the former - which leads to tight coupling with Jamfiles in boostbuild. If it were looked at as the latter, it might be of wider use, this would benefit the author with the exposure he deserves and lead to a higher quality better defined, and tested product. In short, applying the "boost process" to boost tools as well as boost libraries would lead to a similar set of benefits. In the above, I've used examples from bjam, boost book etc. Truth is I don't know the exact current state of all these tools so I maybe wrong on some of the details or my examples may not be the ideally suited to make my point. If that's the case - I'm sorry about that. But, my proposal remains: The "boost process" for libraries is effective in producing better libraries and diminishing wasted effort. Application of the same process to boost tools would be expected to achieve comparable results. Robert Ramey