Re: Google Season of Docs

From: pbristow_at_[hidden]
Date: 2020-04-24 08:28:13

> -----Original Message-----
> From: Boost <boost-bounces_at_[hidden]> On Behalf Of Rene Rivera via Boost
> Sent: 23 April 2020 19:17
> To: Boost Developers List <boost_at_[hidden]>
> Cc: Rene Rivera <grafikrobot_at_[hidden]>
> Subject: Re: [boost] Google Season of Docs
> 
> On Thu, Apr 23, 2020 at 1:10 PM Bjorn Reese via Boost <boost_at_[hidden]>
> wrote:
> 
> > On 2020-04-20 22:52, Rene Rivera via Boost wrote:
> >
> > > My long standing solution is to move the manual reference
> > > documentation
> > as
> > > close as possible to the code itself. For example Predef uses
> > > asciidoctor and has a reference section. Which is embedded in the source
> code...
> >
> > How does this work? Does asciidoctor scan the C++ header files and
> > pick the stuff that looks like asciidoc?
> >
> 
> You have to tell it what parts of the source code, it's language agnostic, to
include
> in your asciidoctor output. <
https://asciidoctor.org/docs/user-manual/#include-
> partial>

IMO the perfect docs toll *must* understand C++ fully in order to provide
quality automatic reference section production.

Doxygen makes a good stab at that.

But Boost libraries docs don't do that much even now.

And I still can't find what I want to know quickly - even when I wrote it!

And yes, Latex is the best tool for writing Math stuff, and we have not really
cracked sucking in formulae properly in Boost.Math, though we have found a
better method recently by converting LaTeX to an SVG image.  Results are pretty,
but it's a hassle still.

Apart from being a yet-another-mark-up-language, what is *really* better about
asciidoc?  Speed?

(I note that there are no instructions on running on Windows - but I suspect one
can).

Paul