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