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

This archive was generated by hypermail 2.1.7 : 2017-11-11 08:50:41 UTC