Boost logo

Boost-Build :

Subject: Re: [Boost-build] B2 documentation..
From: Edward Diener (eldiener_at_[hidden])
Date: 2017-08-08 05:46:46

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.

> So far I've looked at Sphinx and Asciidoctor
> <>. To me Asciidoctor seems like the closer match
> to the QuickBook features. So I'm here for two reasons:
> First..
> I'd like to show an example of asciidoctor docs for B2. The experiment I
> did was two write an new asciidoctor b2 tool. The source for that tool
> has documentation embedded in it. Here's what that looks like:
> <>
> I've incorporated that into the general b2 documentation. By producing
> docbook from that source with the asciidoctor tool and including it as
> one of the appendices. And hence it has the same appearance of the
> general Boost documentation. Here's how that documentation looks like:
> <>
> Second..
> I'm looking for feedback and suggestions. Are there other tools we
> should be considering? What do you think of asciidoctor? Any other
> thoughts with regards to documenting b2?
> --
> -- Rene Rivera
> -- Grafik - Don't Assume Anything
> -- Robot Dreams - <>
> -- rrivera/
> <> (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

Boost-Build list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at