On 17/01/2017 18:06, Robert Ramey wrote:
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.
I used to do it for the PDF files, and it's basically dead simple, and the scripts are still part of the distribution if someone would like to take it on. Given that Docbook now has direct support for ePub output, generating ePub should be as easy as generating html, at least in theory ;)
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.
There are 2 difficulties, one is in setting up the docbook toolchain, then other is that if you want something other than html, then you're going to have to be prepared to do some serious proofreading and tweaking of your documentation. A trivial example, would be large tables that are fine on screen as HTML, but are way too large to fit on a printed page.
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.
+1, there is a lot to be said for consistency. I can't help feeling that too much has been made of Boost using "non standard" or home made tools for this - we don't - the canonical format is Docbook, how you get to that is up to you. You can author the XML yourself (not recommended frankly or all though it does work quite well for small documents), use a commercial editor, or yes use our quickbook tool, something I've always found to be completely reliable and trivial to use. And yes, I resisted it at first too ;) Just my 2c, John