On Tue, Aug 8, 2017 at 12:46 AM, Edward Diener via Boost-build <boost-build@lists.boost.org> wrote:
On 8/7/2017 11:03 PM, Rene Rivera via Boost-build wrote:
As has been mentioned in the past there's the impression that the B2 documentation is lacking. As part of my efforts to move b2 forward I'm looking at option for reworking the documentation. And for various reasons I'm not fond of continuing with the current straight BoostBook/DocBook documentation. My preferred approach is to use a combination of user manual documentation, which we have but needs to be redone, and embedded reference documentation. For the latter I mean having documentation in source code an having a documentation tool extract it and incorporate with the user manual. For Predef I did this with QuickBook extracting from header files. But given the limitations of QuickBook I'm wanting to find an external tool that does the equivalent.

What are the limitations with Quickbook you are finding ? I do not want to start a debate about it but I am just curious why you do not find it adequate for Boost Build docs.


* No general mechanism for extracting embedded docs. Only Python and CPP embedded docs are truly supported (I kludged it for jam files but not completely).
* Limited to BoostBook output. Which limits it to the BoostBook XSLT. Which limits it to one style of documentation.
* No support for fun things like diagrams.
* No easy way to extend it.
* Limited languages for syntax styling.

-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net
-- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail