Subject: Re: [Boost-build] New docs: Go or no-go?
From: Alain Miniussi (Alain.Miniussi_at_[hidden])
Date: 2018-02-27 22:10:48
On 27/02/2018 19:38, Robert Ramey via Boost-build 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.
> 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
Kludgy enough that I've never been able to generate the doc on my
development machine. I stopped trying a couple of years ago. Now I need
to go back to it, can't even remember where to start.
So it is kind of difficult to appreciate points a-g (which could be
valid and seems pretty important).
> 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.
Well, if the new problems are not boost-only non C++ problems, that
would already be an improvement.
Are they ?
> Robert Ramey
> Unsubscribe & other changes:
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