Re: [boost] Google Season of Docs

FWIW, I have converted some libraries to Quickbook and found it quite straightforward to copy and paste plain text paragraphs into a Quickbook section scaffold structure, and then make layout changes and add headings etc. You need a general index, and function, class, macro indexes too that are automatically generated from the Doxygen Syntax comments in the code. Providing snippets of working examples is the most valuable feature - in the knowledge that these really work on all platforms. IOM having lots and lots of examples are the most valuable part of all this. That's what people want - "How do I ... ? " By following examples, and seeking advice, it is pretty straight-forward, if time-consuming. I believe that the user experience is good. Paul

-----Original Message----- From: Boost On Behalf Of Jeff Garland via Boost Sent: 20 April 2020 17:08 To: Boost Developers List Cc: Jeff Garland Subject: 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

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