From: Robert Ramey (ramey_at_[hidden])
Date: 2020-01-01 15:32:21
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.
>> 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.