Re: [Boost-build] B2 documentation..

Subject: Re: [Boost-build] B2 documentation..
From: Stefan Seefeld (stefan_at_[hidden])
Date: 2017-08-09 01:48:33

On Aug 7, 2017 11:05 PM, "Rene Rivera via Boost-build" <
boost-build_at_[hidden]> 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