Re: [Boost-build] B2 documentation..

Subject: Re: [Boost-build] B2 documentation..
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-08-08 03:32:50

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.

> 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 <http://robot-dreams.net/>
> -- rrivera/acm.org 
> <http://acm.org/> (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail
> 
> 
> _______________________________________________
> Unsubscribe & other changes: https://lists.boost.org/mailman/listinfo.cgi/boost-build
>