Re: [Boost-build] B2 documentation..

Subject: Re: [Boost-build] B2 documentation..
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2017-08-08 03:57:23

On Mon, Aug 7, 2017 at 10:32 PM, Robert Ramey via Boost-build <
boost-build_at_[hidden]> 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:

<https://github.com/boostorg/build/tree/feature/asciidoctor/example/variant>

And the resulting HTML page:

<https://grafikrobot.github.io/b2doc/bbv2/examples/build_variants.html>

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