Re: Release Notes: Markdown to replace QBK

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

On 2/17/23 23:35, Vinnie Falco wrote:
> 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.

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.