Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-08-15 17:51:46

On 8/14/17 9:08 PM, Robert Ramey via Boost wrote:
> On 8/14/17 5:34 PM, Glen Fernandes via Boost wrote:

>> Is the Boost.Array documentation not using this?
>> https://github.com/boostorg/array/tree/develop/doc
> 
> Yep - there it is!

I spent a little time investigating this.  As I'm sure everyone is tired 
of hearding I use XMLMind to edit/review docbook and boostbook files. 
Here is what I've discovered.

a) Boost.Array uses the boostbook tags to specify C++ constructs such as 
class, struct, etc within the XML version of the document.

b) These tags are used by the boostbook -> docbook xsl transform to 
generate boiler plate reference documentation.

c) This boostbook xml source has been edited from time to time by hand. 
They aren't ambitious edits so I'm guessing that the work involved was 
not hugely tedious or time consuming.

d) As part of this maintenance, a number of xml elements have been added 
which are not described in the boostbook DTD, Hence as a result, my 
XMLMind editor flags them as illegal boostbook xml tags.  Also these 
tags are not described in the boostbook -> docbook xsl transform, so 
they don't appear in the output.  A simple example of this is a new 
element named "maintainer" to specify the name of the library 
maintainer.  Seems like a perfectly reasonable idea - except that 
without adding provision for this new tag in both the boostbook DTD and 
the boostbook -> docbook xsl transforms, it never appears in any 
documentation output.

e) quickbook developers made the decision not to use these tags.  I'm 
guessing that if there is a DOxygen XML -> boostbook transform somewhere 
in the toolchain, it doesn't use these tags either.  I good decision in 
my view as the boiler plate output for these tags is very much not to my 
taste.

So that is the current situation.  I'm not sure what that means moving 
forward.  I'm sort of thinking:

a) continue minor enhancements to quickboook as they become necessary 
and/or useful.

b) leave the processing of Doxygen -> quickbook/docbook? as it is.  It's 
well know that I consider that Doxgen is harmful to good documentation. 
But until I get everyone else on board with this, it shouldn't be 
changed.  It's easy to avoid using for those who have seen the light.

c) eliminate the usage of C++ specific tags from boostbook, 
boostbook->docbook xsl transforms.  Hmmm - they don't do much harm.  And 
messing with xsl is much worse than working with php - if you imagine 
such a thing.  Also eliminating this would require updating the few 
libraries which use these tags.  Not a bad thing overall, but probably 
not cost effective at this point.

d) One thing that I very much like and think is important is the usage 
of docbook.  This gives access to some important (though kludgy) tools 
and the ability to transform formats and generate PDF, ebook etc.

In sort, simplifying the tool chain is pretty complicated.  But the 
complexity of the tool chain is motivating people to avoid using it 
which I think is a bad thing.  I would hope that some effort can be 
invested in option a) (incremental improvements to quickbook) to make it 
less tempting to move on to something which will only make things worse.

Robert Ramey