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
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk