Re: [boost] Generating Boost documentation with pandoc

Subject: Re: [boost] Generating Boost documentation with pandoc
From: John Maddock (jz.maddock_at_[hidden])
Date: 2017-01-17 14:35:10

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