Re: Google Season of Docs

From: Jeff Garland (azswdude_at_[hidden])
Date: 2020-04-20 16:08:25

 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_at_[hidden]> wrote:

> On Mon, 20 Apr 2020 at 17:19, Glen Fernandes via Boost
> <boost_at_[hidden]> 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
>