Re: Google Season of Docs

From: pbristow_at_[hidden]
Date: 2020-04-20 17:13:11

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 <boost-bounces_at_[hidden]> On Behalf Of Jeff Garland via
Boost
> Sent: 20 April 2020 17:08
> To: Boost Developers List <boost_at_[hidden]>
> Cc: Jeff Garland <azswdude_at_[hidden]>
> 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_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
> >
> 
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost