Re: [boost] Google Season of Docs

I'd be fine with AsciiDoc as well, but I'd say currently at least quickbook appears to be a much more frequent choice. The real question for the thread remains will we have someone do a project to convert xmldocs into one of the 'plain text' alternatives? On Mon, Apr 20, 2020 at 8:36 AM Mateusz Loskot via Boost < boost@lists.boost.org> wrote:

On Mon, 20 Apr 2020 at 17:19, Glen Fernandes via Boost wrote:

...

On Mon, Apr 20, 2020 at 5:11 AM Cem Bassoy wrote:

...

Mateusz Loskot wrote:

...

Cem Bassoy wrote:

...

Is GIL using AsciiDoc?

No, GIL is using reStructuredText and Sphinx, but if I was migrating today, I'd go for AsciiDoc, I think.

Can you shortly elaborate? I am asking for ublas.

If you're interested, we've converted a few Boost library documentation from HTML to Asciidoc. [...] The asciidoctor tool is also fairly easy to run for users to generate this documentation themselves, compared to Quickbook+Boostbook. I'm told it is simpler and easier to run than Sphinx too.

Thank you Glen.

Cem, my first issue with Sphinx is reST which, and Quickbook too, I find not as friendly for a human reader as I do find AsciiDoc. I like Markdown and AsciiDoc feels more like it and offers semantic features that I'm missing from Markdown. I also find Python legacies in Sphinx a bit itching - originally developed for Python, ported to other domains, while AsciiDoc and its tools feel domain-agnostic.

OTOH, some argue Sphinx is more capable than AsciiDoctor here I found a good summary, may be outdated though https://github.com/neovim/neovim/issues/329#issuecomment-56082074

There are some interesting tools for AsciiDoc format, e.g. http://antora.org/

Finally, as Glen explained, some Boost libraries selected AsciiDoc, so it makes sense to me to follow the crowd to be able to share knowledge and any tools and infrastructure that appears in future.

Best regards, -- Mateusz Loskot, http://mateusz.loskot.net

_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost