Re: [Boost-build] B2 documentation..

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 
> <http://asciidoctor.org/>. 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:
> 
> <https://github.com/boostorg/build/blob/feature/asciidoctor/src/tools/asciidoctor.jam>
> 
> 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:
> 
> <https://grafikrobot.github.io/b2doc/extra-tools.html>
> 
> 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 - http://robot-dreams.net <http://robot-dreams.net/>
> -- rrivera/acm.org 
> <http://acm.org/> (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail