Re: [boost] Release Notes: Markdown to replace QBK

On 2/17/23 23:22, Vinnie Falco wrote:

On Fri, Feb 17, 2023 at 12:14 PM Andrey Semashev via Boost wrote:

...

Please no. Markdown is a very limited and poorly documented format.

Well, I have more bad news for you. Quickbook is unmaintained as is its required Boostbook support.

I don't have much problem with that as long as it works. And it does work, and does a much better job than Markdown.

If you think Markdown is unpopular (it isn't) you should see how many projects outside of Boost use Quickbook.

I'm not saying anything about its popularity, it's the last thing that I'm interested in, actually. Markdown is good for some things. Like writing a small simple document, like a readme. But not good enough for library documentation.

Long-term I am moving to Asciidoc and focusing my energy on making sure that Boost authors who want to use Asciidoc have an easy time of it, and get great results.

Asciidoc could be a somewhat worthy replacement for QuickBook if it integrated with Doxygen. But it doesn't, so it doesn't work for me. It does miss a few other QuickBook features that I use, like importing annotated C++ code. But, I guess, those are not as vital.

...

Also, I oppose to having preference to GitHub or any other particular service provider in basic Boost facilities, such as documentation format.

"Github flavored markdown" is not tied to GitHub it just became so insanely popular that it is a widely used dialect. Python's markdown processing tools for example use Github flavored markdown.

It is tied in regards that only GitHub truly knows how to render GitHub Markdown. I tried different tools to convert GitHub Markdown to HTML, some claimed they supported the GitHub flavor, and it wasn't perfect. Though that was a few years ago, and I didn't bother trying since.

...

Boost should be easy to move between service providers.

Fortunately this proposal doesn't change the ease of movement, but I generally disagree with this statement.

Making "Boost easy to move between service providers" has a cost, and that cost is paid by everyone on a continuous basis. Moving to another service provider also has a cost, but it is a singular event with extremely low frequency. Since the majority of our energy is spent on not-moving-to-other-service-provider things, we can afford to make switching service providers expensive as long as we get great value from not worrying about ease of movement.

Choosing a service-independent well-documented format for documentation has no added costs. Especially, when such format is already used. I consider the ability to easily switch service providers an important disaster resilience feature (where "disaster" has a broad meaning).