On Tue, Feb 27, 2018 at 12:38 PM, Robert Ramey via Boost-build <boost-build@lists.boost.org> wrote:
On 2/26/18 1:44 PM, Rene Rivera via Boost-build wrote:
I think I've fixed all the problems I can fix in the new style docs <https://grafikrobot.github.io/b2doc/> for b2:

* Fully updated with develop docs.
* Works offline as well as it does online.
* All the cross-links work.
* Marked up all the code to be syntax colored.

Big question is now.. Go with this or no? Note, that this would be a change for some future release not the current Boost 1.67 cycle.

Hmmm - why are you asking us here?  So far Boost hasn't really prescribed what documentation should be used. So I don't know what you need from us.  I suppose you're just asking for our opinion.

I'm asking here as this is where Boost Build users and developers are. And, yes, what I'm asking for is general measure of "does the content look correct?" and a final "is it ok to move to asciidoctor?"

So here's mine.

Moving away from the boost book system is a very bad idea.

B2 has essentially never used Boost Book (except for the small piece of quickbook for jam docs). So we're not really moving away from Boost Book. What I'm hoping to move away from is direct DocBook XML sources.
  That system has some problems, but we would be much better off fixing those problems then abandoning that for the other ones.  The advantages of the boost book system are:

a) It leverages on the docbook concept of separating documentation content from formatting.

b) This means that once documentation has been prepared, it can be rendered in a variety of formats: ebook, pdf, html, and ... others which may come up in the future.

c) This (mostly) reduces the scale of the library developer's task relieving him of the burden of maintaining some format/rendering.

d) It promotes the maintenance of a consistent view of boost documentation.  It does this to the point that libraries can be rendered individually or as one larger "boost encyclopedia".

e) It would facilitate the automatic creation of a boost "documentation browser" among other things.  Again, rather than each library author making his own documenation table of contents "browser" it would permit tools like this to be inherited by all libraries with no effort expended by library authors.

f) It decouples documentation editing.  There are multiple tools available for editing boostbook including quikbook written by eric neibler, xmlMind which I have been promoting, emacs macros and commercial packages as well.

g) the boost book system is "open" to add on tools and we've made a few that still work. 

I'll concede there are some downsides to boostbook:

a) the b2 build procedure has been "fragile".  But in my view that applies to everything related to b2. But b2 has been "good enough" for lots of boost stuff so I would imagine that this is fixable.

b) the xml syntax is noxious.  I've mentioned ways to deal with this.

c) The docbook tool chain is very kludgy

But moving to something else is just going to substitute a new set of problems for the current ones, and inhibit progress toward a collaborative solution.

Yes, you've mentioned all that before :-) And I concur that all of those are good points. But perhaps you failed to notice previously where I mentioned, and illustrated, taking this same documentation and feeding it into our DocBook processing chain <https://rawgit.com/grafikrobot/b2doc/90a793a12c675059e32ad4b4c77b7d84c2f1ab54/index.html>.

On another point though.. Part of the documentation change is to prepare for making B2 truly independent of Boost.

-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net