On Mon, Aug 7, 2017 at 10:32 PM, Robert Ramey via Boost-build <boost-build@lists.boost.org> wrote:
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. 

I've read it a few times.. And recently I started reading front to back. And there are certainly "issues" with it...
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.

I think it's documentable.. But even if it's not actually documentable, having something is going to be better than nothing. 
  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.

It's definitely not fixed in stone. And part of me writing new tools and writing new documentation is to find the complexities and inconsistencies. And either fix them or document them with warnings (or some combination). 

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.

Embedded documentation is definitely *not* for what you call "semantics". That's what a user manual is for. But right now there's a lot in b2 that is "not documented" in the sense that it's not in the HTML. Although much of it is in comments in code. But as I've seen over the years.. The CLI "--help" system is just not used by users. And I don't blame users, that's entirely my fault (I mean that personally as I wrote that system). My plan for docs is to bring to light that existing documentation and improve it along the way (as above to deal with implementation issues also) and to add documentation, and visibility, to all the built-in tools and utilities that are currently "hidden". I also hope that this style will make it easier for outside contributions. As has been the case for Predef.

There's one more item that might be relevant given your mention of documenting "features" and "semantics".. One common way to do that is through examples. I had previously also experimented with the same manual+embedded documentation but for the existing examples, but with QuickBook. Here's source for one of the cleaned up examples:


And the resulting HTML page:


I know you have ideas on how to write documentation.. And I might get the chance to hear about them at CppCon.. But this is what has worked for me.

-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net
-- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail