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. 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:
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 -
http://robot-dreams.net-- rrivera/
acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail