Re: [Boost-build] New docs: Go or no-go?

Subject: Re: [Boost-build] New docs: Go or no-go?
From: Robert Ramey (ramey_at_[hidden])
Date: 2018-02-27 18:38:42

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.

So here's mine.

Moving away from the boost book system is a very bad idea.  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.

Robert Ramey