Boost logo

Boost :

Subject: Re: [boost] Generating Boost documentation with pandoc
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-01-17 13:06:30


On 7/22/16 6:40 AM, Vinícius dos Santos Oliveira wrote:
> Has anyone tried to generate Boost-styled documentation using pandoc?
>
> I never fully liked PDF documentation because I never actually print
> documentation. However, a few weeks ago I got an ebook reader and I've been
> fascinated by the ePUB format. I'm using it to read even the IETF's RFCs
> and it's very pleasant. I'm using ePUB to read files even on my usual
> laptop.
>
> Anyway, I was wondering how nice would be to have an ePUB file containing
> the whole Boost documentation.

I have created ePUB documents from boost book documentation. It
requires more fussing around that one might hope. But it does work well
in the end - without changing of any of the boost book files.

BTW - I do this without using boost build - just calling a short shell
script. It's very doubtful to me that pandoc can actually do this as
well.

I'm also somewhat doubtful that one could create an ePUB for all the
boost libraries. I might be wrong as it has been claimed that this has
been done for PDF. If it can be done for PDF it can likely be done for
ePUB as well.

But getting the details setup correctly can be very time consuming. Of
course changing to some other system is not going to make that any easier.

DocBook has been around for quite a while and is still widely used. It
has worked well for Boost, and I think all libraries should use it.

>
> pandoc has docbook support as one of its input formats and is capable of
> generating great ePUB output.

Hmmm - I'm skeptical but I'll look into this. The main concern I have
is that getting the documentation exactly right will usually require
some xslt transform along the way - I'll look to see how pandoc handles
that.

A big problem with ideas like this - switching to another documentation
or build system is that they are simpler for smallish examples. But
they often falter when applied to much more elaborate and complicated
examples such as boost libraries. This is often not appreciated by
those who haven't had to actually apply these ideas to these larger
problems.

Robert Ramey


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk