On Aug 7, 2017 11:05 PM, "Rene Rivera via Boost-build" <boost-build@lists.boost.org> wrote:

> I'm looking for feedback and suggestions. Are there other tools we should be considering?

I fully agree with what others have said about sphinx (and docutils / ReST as the underlying technology).
Popularity aside, I believe it is an enormous advantage for a tool to have many users, as that makes it likely that the tool is well tested and supported (e.g. by those same users).

> What do you think of asciidoctor? Any other thoughts with regards to documenting b2?

Perhaps that's just reflective of my own way to learn new tools and languages, but one type of documentation I'm often missing is one on a conceptual level. And while there is some glossary with terms and concepts, this is not nearly as complete in its description as would be necessary to allow me to reason with these terms.
Just look at the ongoing discussion between Steven and myself (mostly just about how targets are defined and how information "flows" between them in terms of features /properties).
For any but the most trivial use cases, this seems quite important information indeed (and also from judging from questions other users have, either about behaviour they seek or error messages they try to comprehend).

(My believe that the underlaying model is more complex than necessary is one of the main driving forces for my working on Faber... :-) )

    Stefan