Hi Everyone, This is to ask for help with building QuickBook documentation, but also to spill my frustration. I would like to offer some feedback in connection with the recent "the future of Boost" threads: about the entry barrier for someone who wants to contribute to Boost. I maintain Boost.Optional. Getting my environment to the point where I was actually able to apply modifications to the official repo took some time, but it has been working fine since. Modifying the source files, so that they compile on multiple compilers, platforms and versions, including C++03 is the easiest part. Testing is a bit harder, but basically works also: I go to folder `test`, run the `b2` command, and it is done. But updating the documentation is the most difficult task for me. Not the content -- this is easy -- but the process/pipeline/framework. I inherited the documentation in QuickBook format, which as I understand was the recommended way for providing documentation for Boost libraries. Maybe it still is? (but I see more and more docs being rewritten to AsciDocs.) I understand that library authors have the freedom to choose their own format of docs for their libraries, but does boost recommend (as opposed to enforcing) one format? Anyway, in order to test if my QuickBook dos are correct, I need to build HTML version from the sources. Sometimes it "just works" with `b2` command, but when something goes wrong, this becomes a pain. I cannot just call `b2` for my library, because apparently my Fedora comes with preinstalled version of b2 (4.4) which appears to be incompatible with something in Boost libraries sources, as I get error: error: mismatched versions of B2 engine and core
error: B2 engine (b2) is 4.4.1 error: B2 core (at /home/andrzej/Repos/boost/tools/build/src) is 4.9-git
Ok, I learned to live with it and to launch b2 from tools/build. It used to work for a while, but yesterday when I did a `git pull --rebase` on Boost repo, it no longer works. I get an error: Jamfile.v2:45: Unescaped special character in argument
<format>pdf:xsl:paramboost.url.prefix= http://www.boost.org/doc/libs/release/libs/optional/doc/html Performing configuration checks
- default address-model : 64-bit (cached) [1] error: at /home/andrzej/Repos/boost/tools/build/src/kernel/modules.jam:106 error: Unable to find file or target named error: '/boost/architecture//mips' error: referred to from project at error: '.'
Ok, I can remove line `: /boost/architecture//mips` from file `boostcpp.jam`. (Am I supposed to do it before using `b2`?). But then, when trying to build the docs, I get a lot of errors, saying: runtime error: file
/home/andrzej/Repos/boost/tools/boostbook/xsl/annotation.xsl line 432 element element xsl:element: The effective name '' is not a valid QName.
(Full error message is enclosed.) I have no clue which element in the pipeline is causing or reporting this. QuickBook, BoostBook, DocBook, xsltproc? The process involves many components, at least according to this diagram: https://svn.boost.org/trac10/wiki/BoostDocs/GettingStarted Is this something obvious that I am missing? Is this a good idea, or a recommended practice to use QuickBook nowadays for Boost docs? I feel comfortable fixing or writing C++ code, and I am willing to devote some of my limited time to do this. But fighting with QuickBook documentation is something I would not rather do. I have a small library that I considered submitting to Boost: https://github.com/akrzemi1/markable But as long as it is on my GitHub page, it is simple to maintain, test and document. If I imagine how many nights I will have to spend making the documentation compatible with Boost, or getting all the b2-related stuff to work, I feel discouraged. Maybe I am being unfair to `b2` now. But it is certainly my personal emotional impression. I do not mind the current Boost website format or the underlying technology. I do not mind the mailing list format. My primary obstacle is this perceived or real difficulty to get a boost library into a shape where it just builds, including its documentation. My ideal as a Boost library maintainer, is that I just provide the source for the library and the documentation, and anything else "just works". Maybe this is not achievable, but the closer to this ideal, the more encouraged I would be to consider authoring or maintaining a library. Any help in fixing my build problem is most welcome. Regards, &rzej;