Re: [boost] Generating Boost documentation with pandoc

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