Re: [Boost-build] B2 documentation..

Subject: Re: [Boost-build] B2 documentation..
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2017-08-08 12:23:29

On Tue, Aug 8, 2017 at 12:46 AM, Edward Diener via Boost-build <
boost-build_at_[hidden]> 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.
>

Briefly..

* 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