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