Re: [boost] Recommendations for documentation authors

On 1/3/24 1:28 AM, René Ferdinand Rivera Morell via Boost wrote:

On Tue, Jan 2, 2024, 12:00 PM Vinnie Falco via Boost wrote:

...

Now here is one datapoint which pretty much speaks for itself:

Peter Dimov and René Ferdinand Rivera Morell use Asciidoctor ( https://asciidoctor.org/).

An additional point.. I was one of maintainers Quickbook, boostbook, and the b2 support for them. And I gave up on them long ago because of the huge difficulties in the tools.

I find asciidoctor to be well maintained and very flexible in it's features. All documentation I write now is with asciidoc including: b2, predef, a variety of wg21 papers, and many more. Key features I like: I can write reference docs directly in the cpp source code, I can include images and SVG, I get live render in vscode.

I am the original author of Quickbook. I too have difficulties with the B2, Quickbook, Docbook toolchain and at one point, I just gave up. Now, I too have moved on, and in my newer libraries, I am now also using Asciidoc and Antora. It's far from perfect, and I do miss some of the features of Quickbook such as macros and extracting documentation from cpp source with callouts via [import source.cpp] (*). But as Rene said, Asciidoc is well maintained. (* aside * René, I did not know you can write reference docs directly in the cpp source in Asciidoc. How do you do that?) Here's an example of one my latest libraries: https://cycfi.github.io/q/q/v1.0_beta/reference/synth.html Interestingly, I learned about Asciidoc here, while lurking every once in a while. Quickbook was last maintained by Daniel James up to around 2018. After that, it seems no one picked it up anymore. Sometimes I wonder about modernizing it, but I don't think I want to end up maintaining tools anymore. What's funny is that in the Introduction, I had this quote: “Why program by hand in five days what you can spend five years of your life automating?” -- Terrence Parr, author ANTLR/PCCTS Now I say, five years is an understatement. But life moves on, I suppose. Regards, -- Joel de Guzman