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 15:46:48

On 1/17/17 11:35 AM, John Maddock wrote:

> 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.

Right.

I think that these problems could diminished by not trying to make a 
giant "book" (PDF, ePUB, or whatever) from all the libraries but rather 
to to build each library independently. This would eliminate the 
requirement that everyone be exactly on the same page.

Another unfortunate feature if the current system is that it depends up 
using b2 which is really overkill and a big pain for the casual user. 
(Actually any user).  In the incubator I've shown how to create pdf and 
epub documentation for a particular library just using the tools out of 
the box and a couple of 1/2 line shell scripts. Promoting this way of 
building the docs would go a long way to quell the calls for mucking 
around with current system.

>> 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.

Personally I'm not less concerned about consistency that others.  My 
concern is simplicity.  I investigated all the alternatives I could find 
in giving my advice to authors in the boost library incubator. Correct 
and complete documents are not trivial so the "lightweight" solutions 
didn't suit me. I came up with boost build but without b2.

> 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.

Right

> 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 ;)

I resisted it because I didn't want to become dependent on boost tools. 
b2 burned me.  I turned to XMLMind which is great as far as I'm 
concerned.  So my tool chain is:

XMLMind - edit
xml tools xslt and boostbook/docbook to produce html and ePUB
fop - to produce pdf

I'm pretty pleased and it works great outside of boost as well!

>
> Just my 2c, John

+1c from me.
>

Robert Ramey