On 8/7/17 8:03 PM, Rene Rivera via Boost-build wrote:

as a habitual complainer about boost b2 and boost documentation in
general, I'd like to make some observations.

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.

I recently had occasion to study the Boost B2 documentation we currently have.  It's actually OK - particularly in the documentation of commands and such. 

But in trying to move on to other concepts in b2 itself, searching for jamroot, *-config.jam etc, it falls short.  I don't think this is actually documentable.

  When trying to describe how b2 works, one is going to discover that b2 is too inherently complex and should be restructured to make it more understandable.  If b2 is considered
fixed in stone, you won't be able to document it.

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.

I believe that, after much effort, this will yield disappointing results.  It might work for the commands and rules built-in, but these
are already OK.  It won't work for the really hard part of b2 - features, properties syntax and semantics.