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 16:27:10

On 7/22/16 12:58 PM, Stefan Seefeld wrote:
> 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.)

My point is ..  I'm just wondering about the value of such an effort.  I 
think it's great that you want to make something better, I'm just 
suggesting you consider the best return on your efforts.  I don't see 
how enhancing DocBook would have anything to do with boost.

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

right.

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

right.  but someone still has to do it, test it, take responsibility for 
keeping it working, explain it, etc.  I think this would be a very 
worthwhile project that I'm encouraging you to undertake.  I think it 
would have a significant positive impact on boost you'd get a lot of 
satisfaction from making a success of such an effort.

If I understand correctly, creating epub output would skip over entirely 
the whole FOP rendering which complicates the process and seems to have 
some issues of it's own.

To make this effort successful, one would likely have to enhance the 
description of how to do.

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

Hmmm - interesting, I never knew about this.

> I'm looking into pushing this into master, so it
> can be distributed with DocBook itself (as an extension grammar).

I'm not sure what this means, but sounds worth considering.

Robert Ramey