Re: [boost] Improving Boost Docs

Subject: Re: [boost] Improving Boost Docs
From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2017-08-16 15:09:03

On Wed, Aug 16, 2017 at 8:03 AM, Robert Ramey via Boost
<boost_at_[hidden]> wrote:
> b) The inclusion of all the specialized tags for C++ like class, struct, is
> meant to automate the production of boiler plate output for those C++
> constructs.  I understand the appeal of this - we're computer programmers
> and want to automate everything - but in this case it's a bridge too far.
> quickbook doesn't use these - a good choice in my opinion.  A few hand
> edited boost book do uses these but the results are not satisfying in my
> opinion.  To improve them, one would have to wade into XSL language - a
> place were few people want to go.

And again I will use this opportunity to point out that I have "gone
there" by creating "docca", an XSL library which provides the
component for transforming Doxygen XML output into QuickBook:

<https://github.com/vinniefalco/docca>

Beast uses docca directly to generate its reference section.
Everything linked from this reference index was generated using
Doxygen + docca:

<http://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/quickref.html>

(The index itself is hand-written).

I realize of course that this style of reference is not suited for all
types of libraries. For example, it would not do very well with mp11
or Hana. But for a more traditional library that has mostly concrete
types and functions it works pretty well. Note that Asio uses an
identical toolchain (well, I copied it).

If anyone is interested in a docca integration for their library, to
generate a reference from Javadoc comments in the code using Doxygen,
I would be happy to help.

Thanks