Subject: Re: [boost] Improving Boost Docs
From: Edward Diener (eldiener_at_[hidden])
Date: 2017-08-15 19:54:49
On 8/15/2017 1:51 PM, Robert Ramey via Boost wrote:
> 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?
>> 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
> 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.
What ! Robert Ramey admitting that quickbook is not evil ? Thanks
Robert, for at least investigating this and deciding that quickbook is
usable, even if it is not your preferred choice. Maybe you can do the
same with doxygen <g>. Whatever your objections it is eminently usable
also, even while it is not perfect.
> Robert Ramey