Re: Recommendations for documentation authors

From: Joel de Guzman (djowel_at_[hidden])
Date: 2024-01-03 14:25:26

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 <boost_at_[hidden]>
> 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