Re: [Boost-build] B2 documentation..

Subject: Re: [Boost-build] B2 documentation..
From: Raffi Enficiaud (raffi.enficiaud_at_[hidden])
Date: 2017-08-08 09:18:24

Le 08.08.17 à 05:57, Rene Rivera via Boost-build a écrit :
> On Mon, Aug 7, 2017 at 10:32 PM, Robert Ramey via Boost-build
> <boost-build_at_[hidden] <mailto: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.

Hi there,

I think this is nice. So during my time trying to understand b2, I think 
I have a hard time understanding the "modules", like when/how the python 
extensions are working and what to call in order to include that in your 
build directly.

If you are keen on using asciidoctor, fine. However, I believe that 
Sphinx is in overall a much better investment, and has a wide support.
CMake (sick) documentation is written in Sphinx, using standard RST 
markup and a dedicated parser, and I have to say it works quite well 
(also, this extension should be just in python and easy to maintain).

Things to consider are to me the following:

* the overall markup:
   * this should be accessible or at least big enough to have a wide 
acceptance and promote contributions. I have to say I've never heard of 
asciidoctor so far, while ".rst" can be at least reused in several 
projects and is likely to have a better spread. Quickbook is not widely 
known, but is quite simple to handle.
   * the markup should be easy and powerful. I experienced Docbook and 
it is not easy at all, and quite error prone (think about cross 
references). I do not like .rst but this is easy. I like Quickbook a lot 
as well. Doxygen is not really easy because error prone, but at least 
provides logs/diagnostic.

* the features provided
   * is the markup rich enough, in particular for external links, 
embedded code, cross references, sectioning, etc
   * can you change easily the layout, and help the user navigate 
through the documentation nicely? In the current state of b2 doc,
   * can you generate PDF/offline doc which does not look like crap?
   * can you have a search?
   * can you generate an index easily, and play with the structure of 
the documentation? Can you easily change the structure? For instance, in 
Quickbook, restructuring breaks the URLS if you link to eg. section by 
the name in the documentation tree. In Sphinx, you have commands like 
:py:class:`` that references a global object, wherever it is in the 
documentation.
   * etc

* the (lack of) interplay with other tools. In boost, we have 
quickbook+doxygen that play together "so-so" I have to say. I personally 
still do not know what are the steps to generate a doc with mixed 
quickbook+doxygen, and this is like a black-box that is written in 
stone. The result is what it is (the reference sections are quite poor) 
and nobody is really able to maintain the dox+quickbook bindings. The 
requirements of having your documentation tool working well with another 
one for me is causing a lot of troubles, so I would rather go for a tool 
that can do almost everything. Quickbook cannot (eg. parse source code), 
I do not know about asciidoctor, I know that Sphinx can do this and in 
that regard is a rather complete solution.

Just my thoughts.

Cheers,
Raffi