Re: [boost] Google Season of Docs

-----Original Message----- From: Boost On Behalf Of Rene Rivera via Boost Sent: 23 April 2020 19:17 To: Boost Developers List Cc: Rene Rivera Subject: Re: [boost] Google Season of Docs

On Thu, Apr 23, 2020 at 1:10 PM Bjorn Reese via Boost 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