On 1/1/20 4:03 AM, Richard Hodges via Boost wrote:
And it's Doxygen to XML, XML to Boostbook. Then of course Boostbook to Docbook, and Docbook to HTML.
Doxygen to XML, Renders Doxygen meta information in a form that it can be combined with something else. Presumable this is done by some Doxygen defined magic. XML to Boostbook - BoostBook is DocBook with a bunch of extra tags for handling C++ specific vocabulary types. The hope would be that this extra "semantic" information would permit facilities like better generation of things like better cross reference information, better formating of C++ "things" - like typenames vs variable names, vs examples, vs .... Boostbook can and does get created different ways: Doxygen, QuikBook, by hand, by XMLMind (in my case) and perhaps other ways I'm not familiar with. Not everyone actually uses BoostBook tags. Strictly speaking it is not necessary as it's an extension of DocBook. BoostBook->DocBook (xslt) - converts the special boostbook tags to more generic DocBook tags. DocBook -> html, pdf, etc.. (xslt, fop, ...) - renders the Docbook in a device specific format. So the question is: Which of the above steps is superfluous? Which do you think you can eliminated. Or do you want to consolidate them to eliminate steps? But composing the above steps is much simpler than than trying to do it in less steps. Time spent to execute the above steps is not significant in the scheme of things.
Other than the very pleasing boost documentation styling, is this seemingly convoluted conversion route necessary? Is it not possible to configure a Doxyfile to contain the correct styling?
I do not believe that Doxygen can be configured to capture semantics of much of C++ code to generated reference documentation. And of course that doesn't even touch upon other necessary things like narrative, examples, references, illustrations, etc.
I have no knowledge of the evolution of boost documentation and have no axe to grind, but as a newcomer it seems to me that there is a lot of 'unnecessary' compication in the production of documentation.
Right.
I appreaciate that there's no real sense in revisting existing libraries, but for new ones wouldn't it be prudent to choose the shortest possible path which involves the least learning and maintenance?
LOL - feel free to suggest another path. Robert Ramey