-----Original Message----- From: Boost <boost-bounces@lists.boost.org> On Behalf Of Richard Hodges via Boost Sent: 1 January 2020 12:03 To: boost@lists.boost.org List <boost@lists.boost.org> Cc: Richard Hodges <hodges.r@gmail.com> Subject: Re: [boost] Recomended way of generating documentation
Treading carefully here as I'm new to boost library maintenance...
So that you can cross-reference the Doxygen reference with whatever other documentation you have
http://www.doxygen.nl/manual/autolink.html suggests that links to external URLs are recognised by doxygen. Presumably linking to the correct place vis-a-vis release/developer builds can be controlled with a macro in a generated Doxyfile?
And it's Doxygen to XML, XML to Boostbook. Then of course Boostbook to Docbook, and Docbook to HTML.
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 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?
It depends on the size of the documentation. For 'trivial' documentation, the Doxygen and Markdown combination is acceptable, but I believe strongly that the best Boost documentation is done using the Quickbook toolchain (including Doxygen syntax comments to provide a references section). A killer feature of Quickbook is the ability to include code snippets from actual C++ examples that can be run, ensuring that what you get is what compiles and runs. As a mark-up language Quickbook is pretty obvious (apart from the gotcha of using indent-spaces as a way to add code sections - a common but quick'n'dirty markup feature that can cause some confusion). Paul