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

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: 
> https://lists.boost.org/mailman/listinfo.cgi/boost-build