Re: Release Notes: Markdown to replace QBK

From: Vinnie Falco (vinnie.falco_at_[hidden])
Date: 2023-02-17 20:35:44

On Fri, Feb 17, 2023 at 12:24 PM Andrey Semashev via Boost
<boost_at_[hidden]> wrote:
>...

It is interesting how after spending years on the list, I discover
that certain subjects bring up predictable responses :)

> I'm not going to convert any in-library release notes I maintain to
> Markdown.

No one is asking you to. This proposal would have you use markdown
instead of Quickbook in the combined release notes which are prepared
for each release, such as in this file which will be used for 1.82.0:

<https://github.com/boostorg/website/blob/master/feed/history/boost_1_82_0.qbk>

> I currently have to convert HTML to QuickBook for Filesystem,
> and this isn't fun.

Oh I agree with you 100%

> I'm not going to do this for every library now.

No one is asking you to. This proposal does not change how you write
or produce your library documentation. This proposal does not require
changing anything in your repository. Peter's proposal however, does
require adding and maintaining a new markdown file in your repo.

> And I sure won't ever convert docs to Markdown either.

No one is asking you to. However the chances are good that at some
point in the future, Quickbook and Boostbook might no longer work
because they receive little to no maintenance. If there are errors
when your documentation builds, you might have to fix this toolchain
yourself. Furthermore, libraries which use Asciidoc are going to
experience a significant upgrade in terms of the appearance and
functionality of their rendered documentation. Libraries using
Quickbook will not have these upgrades. They will be stuck using the
old stylesheets which don't have dark mode, no side table of contents,
and do not look well integrated into the website. Whoever wants these
improvements would have to go into the Boostbook style sheets and fix
them. And so on.

Thanks