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

Subject: Re: [Boost-docs] Query regarding boostbook and documentation
From: Stefan Seefeld (stefan_at_[hidden])
Date: 2016-01-04 22:54:05

On 04.01.2016 11:11, Robert Ramey wrote:
> 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.

Why not ? (To be perfectly clear, I'm not proposing to augment the
DocBook 5 "core" vocabulary with the BoostBook tags. But since DocBook 5
already uses namespaces, it's easy to simply put this new vocabulary
into its own namespace, as a "DocBook 5 profile" (or "extension"). And
in fact, that's exactly what the previous GSoC work did.

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

Yes, some conversion stylesheets will definitely help with the
transition. But we aren't there yet, so it's a bit premature to think
about the details (other than the process in general).

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

Yes, QuickBook would need to adjust. But given the (expected) one-to-one
mapping from BoostBook to whatever the DocBook 5 extensions will be
called, I don't think this is going to be a big deal.

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

Yes, I second that. XMLMind's XXE is a wonderful tool that has saved me
a lot of time authoring DocBook content. The best I have seen, actually.

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

It may not be better for you, if you are already familiar with the
existing tools. But it will be better for someone who

a) doesn't know BoostBook yet and has to learn yet another tool
b) doesn't know Boost at all but would like to use this on entirely
different projects, without wanting to install Boost first.
c) uses DocBook 5 and doesn't want to move back to DocBook 4
d) wants to use standard tools and languages that are maintained by a
wider audience.

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

I agree. Putting BoostBook "into the open" may actually help with this,
too, as it frees you (and other Boost developers) from having to
maintain your home-grown tools.

    Stefan

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