Re: Release Notes: Markdown to replace QBK

From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2023-02-17 20:41:52

On 2/17/23 23:22, Vinnie Falco wrote:
> On Fri, Feb 17, 2023 at 12:14 PM Andrey Semashev via Boost
> <boost_at_[hidden]> 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).