On Thu, Sep 11, 2025 at 1:41 PM Nana Sakisaka <aroma.slope.seven@gmail.com> wrote:
There is a long-standing request to make the X3 docs more "visible" to users
Oh... yes, that is a problem. I myself did not realize that Spirit was actually three separate libraries, and that the move to C++23 only affected one of them (?) My opinion, this needs to be split up physically into individual libraries so they can each evolve and be maintained independently (or not maintained, such as in the case of old X3 maybe?) We have been working on supporting the Asciidoctor and Antora toolchains to provide a modern option for Boost library documentation, as the current Quickbook is receiving little maintenance (in some cases no maintenance). Quickbook is a long-term existential risk for Boost library documentation. Antora looks like this (with our custom UI and stylesheets): https://www.boost.org/doc/libs/master/doc/antora/url/index.html A benefit is that Asciidoctor is a popular markdown format which enjoys wide support. GitHub for example, renders previews for adoc files as you can see here: https://github.com/boostorg/json/blob/develop/README.adoc And the Alliance provides infrastructure so that pull requests show documentation previews before they are merged: https://github.com/boostorg/url/pull/861#issuecomment-2328039431 As Joel suggested, please continue the discussion on the GitHub link I
mentioned above. We should stop splitting our discussion into various places.
Joel suggested both GitHub issues and the mailing list. GitHub issues have their place yet they lack the greater visibility to the rest of the contributor community. I think a discussion of splitting up libraries and available new tooling for documentation is something of interest and important to a wider audience. I apologize if I came across as heavy handed in some of those issues. I think the problem here is that months of changes and intentions which impact other things came out of nowhere. Perhaps when a new maintainer is appointed for a library there could be a formal introduction to the mailing list, and the new maintainer receives some kind of instruction so they can learn about customs such as the mailing list, the desire to avoid breaking existing users, and the encouragement to maintain a two-way dialog when making big changes. Maybe it is not too late to do this? Thanks