Re: [boost] Improving Boost Docs

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?
>>> 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.

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