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-05 00:50:10

On 1/4/16 2:54 PM, Stefan Seefeld wrote:
> 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.

Maybe I've mis-understood.  If you mean you create a new schema for 
BoostBook which includes DocBook5 - just like BoostBook currently 
includes DocBook4 - I see no problem.  I still can't imagine you're 
going to edit DocBook5 itself.

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

But I don't see what all this work is going to get us.

> 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

They will still have to learn the new BoostBook

> b) doesn't know Boost at all but would like to use this on entirely
> different projects, without wanting to install Boost first.

That's one think I did in the incubator.  I didn't want to depend on 
boost build.  So I extracting the information from the boost build 
macros and made a couple simple build scripts which do the 
transformation via xslt into html.  For an example one can checkout the 
safe numerics library which builds "boost-like" documentation without 
boost tools at all.

> c) uses DocBook 5 and doesn't want to move back to DocBook 4

As I've said, I don't really know the difference between DocBook4 and 
DocBook5 and BoostBook as the xmlmind editor just keeps track of what's 
legal in every context - I just have to point an choose among the legal 
tags.

> d) wants to use standard tools and languages that are maintained by a
> wider audience.

Halleluha -  I'm for that.  Though I don't know if docbook  5 is used 
more than docbook 4.

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

The main problem is that few developers understand the role of type 
requirements in library design and how to document them.  This is 
independent of the documentation toolset.

Robert Ramey
>
>      Stefan
>
>
>