Re: [Boost-docs] Query regarding boostbook and documentation

Subject: Re: [Boost-docs] Query regarding boostbook and documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2016-01-04 16:11:22

On 1/4/16 5:04 AM, Stefan Seefeld wrote:
> On 04.01.2016 01:35, Robert Ramey wrote:
>> On 1/3/16 4:02 PM, Stefan Seefeld wrote:
>>> I know this isn't what Boost itself is using right now. Hopefully, once
>>> the above is completed, Boost may switch to free itself from having to
>>> maintain yet another home-grown tool / language.
>>
>> what does thie mean exactly?
>
> It means that - ideally - the document schema (and tools) now known as
> "BoostBook" should become part of DocBook,

You mean you're going to enhance DocBook so that it incorporates tags 
from BoostBook?  I don't think you mean that.

Or do you mean that you're going to remove the BoostBook tags and use 
only tags from DocBook5?  I could see this, but I'm not sure how much 
work it would take to convert all the existing BoostBook xml. (maybe it 
would be easy with the right xslt magic?).

But doesn't quickbook generate BoostBook xml?  So you'd have to re-write 
that too?

> freeing Boost developers to
> focus their attention on library design rather than support tools. And
> it means that - again, ideally - more people will be able to benefit
> from all of that work, not just Boost developers.

I should say that using XMLMind to edit BoostBook XML has worked very 
well for me.  It's WYSIWYG so you can see what you're doing, It works 
with the BoostBook DTD and supports inclusion of images and code so I 
have no need to use more than that one tool. That is, no doxygen, 
quickbook, and ? I also created some documentation templates so that a 
large part of creating standards conforming documentation is almost a 
matter of form-filling.  Nothing
is perfect of course, but for me it has made documentation preparation 
and maintenance (especially) a relatively easy task which contributes to 
the development process rather than bogging it down.  It's explained in 
the www.blincubator.com and it's used to create and maintain the 
documentation for the safe numerics library.

> Technically it means that Boost documentation will be able to depend on
> DocBook 5, rather than remaining stuck with an old DocBook 4 version
> against which the BoostBook DTD was developed.

And how will that be better.  I'm not against it, I just don't want to 
go through turmoil without ending up with something better.

To me, the main problem with boost documentation is that most boost 
authors (and developers in general) don't know how to write it.  And it 
seems they don't know this.  To most is just an afterthought and a chore 
rather than a design activity. Of course the kludgy tools don't help 
here.  I would like to see more effort addressed to this area,  I've 
layed out my ideas in the incubator in requirements and simple tools.  I 
know I continually harp on this and I'm sorry I do this.  But I see this 
as a big bottle neck in the development of quality software.

Robert Ramey