Re: [boost] Generating Boost documentation with pandoc

Subject: Re: [boost] Generating Boost documentation with pandoc
From: Robert Ramey (ramey_at_[hidden])
Date: 2016-07-22 15:45:13

On 7/22/16 11:25 AM, Stefan Seefeld wrote:
> BoostBook was invented inside Boost, but to a large extend is useful
> outside of Boost. So a few years ago we started an effort to
> "standardize" it, i.e. merge it (and by "it" I mean the schema as well
> as the stylesheets) into the DocBook project itself.
> (Note that some of the BoostBook are actually too specific for a wider
> audience, but the parts that aren't should eventually be available as
> part of DocBook.

OK - so this is a DocBook project rather than a Boost project.

But the version of DocBook that boost uses is DocBook 4 and uses a DTD 
schema.  The more current version of DocBook is 5.0.  DocBook 5.1 is 
specified but the last complete reference is DocBook 5.0.  And interest 
in DocBook has seemed to have waned. Of course it's not going to 
disappear as a lot of stuff is made for it.  And, though I hate XML, it 
does a good job of factoring out the meaning of the document elements 
from that of the formating.  I think it was a good choice for BoostBook 
to be a specialized version of DocBook which includes transforms from 
BoostBook to DocBook.

I think that enhancing the BoostBook tool chain might be a worthwhile 
and doable task.

a) add enhancement to produce epub.  I think this wouldn't be too hard 
and would be useful.

b) Consider translating BoostBook to DocBook 5.0.  Again, I think this 
might be worthwhile and it might easily doable.

c) Consider dropping BoostBook entirely and using DocBook 5 directly.  I 
wonder if the special tags for BoostBook are all that useful.  The work 
is done so it's not a big issue.  I've made some documentation in boost 
book and some in DocBook 5 and I don't see a huge difference from the 
author's point of view.  Using DocBook direclty, would make the tool 
chain smaller and simpler.  Of course such a task would of necessity 
require an update of quickbook ....

>
>         Stefan
>
>