Re: [boost] Generating Boost documentation with pandoc

Subject: Re: [boost] Generating Boost documentation with pandoc
From: Stefan Seefeld (stefan_at_[hidden])
Date: 2016-07-22 15:58:59

On 22.07.2016 15:45, Robert Ramey wrote:
> 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'm not entirely sure I see the point you are trying to make. (I should
clarify: the "standardization" effort I'm talking about means to take
the 95% of BoostBook that are generic and produce an RNG grammar from it
that extends the DocBook 5.x RNG grammar.)

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

By "toolchain" I assume you are referring both to the actual tools
(xsltproc, dblatex, fop, etc.), plus the stylesheets. Note that the
tools are all standard tools anyhow, only a few stylesheets (those that
translate BoostBook to DocBook) are not (yet).

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

That shouldn't require any changes to the "toolchain". Just changes to
the build system.

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

This has been done years ago, on a DocBook branch (that was a GSoC
project I mentored). I'm looking into pushing this into master, so it
can be distributed with DocBook itself (as an extension grammar).

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

I'm all for using "standard" tools. But I do see quite some benefit from
using the enhanced vocabulary provided by BoostBook, which is why I have
been championing the inclusion of it into DocBook proper.

On the other hand, if we are talking about an intermediate format only
(which is generated from quickbook), all this is moot. All that counts
is the initial "source" and the final output. But that would just push
the problem around: you then have all the maintenance headaches as part
of quickbook...

    Stefan

-- 
      ...ich hab' noch einen Koffer in Berlin...