[Boost-build] B2 documentation..

Subject: [Boost-build] B2 documentation..
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2017-08-08 03:03:17

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:

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