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