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

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

On Fri, Feb 17, 2023 at 12:24 PM Andrey Semashev via Boost 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.qb...

...

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.

If the Boost-wide release notes are written in Markdown, I will have to convert the in-library release notes written in QuickBook (that I gradually write during the development cycle) to Markdown. I don't want that. Currently, I can mostly copy-paste the in-library release notes into Boost release notes, with some minor tweaks to fix links to issues and PRs.

...

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.

I'm mostly fine with how QuickBook docs look currently, thanks. I have my wishes, but those are not about appearance, like dark mode and such. Side ToC would be nice, but lack of one does not outweigh the drawbacks that Markdown and other tools bring.