Re: [boost] Boost documentation

From: Gennadiy Rozental (gennadiy.rozental_at_[hidden])
Date: 2007-06-23 21:26:13

"Joel de Guzman" <joel_at_[hidden]> wrote in message 
news:f5j3pq$ba4$1_at_sea.gmane.org...
> Gennadiy Rozental wrote:
>> Hi,
>>
>> I've been offline for a bit. But I was able to spend several weeks 
>> learning
>> DocBook. I must say I was really impressed with quality of this project. 
>> I
>> also tried to get a grasp of BoostBook and gave perfunctory look on
>> quickbook. Here I would like to share my thoughts on recent "doc update"
>> movement.
>>
>> I. quickbook as documentation media.
>>
>>   Why, oh, why don't we learn from our own mistakes. We just started to
>> realize the problem we got ourselves into with makesystem. And 
>> immediately
>> find new toy to play with. However fun it is, however cool it might look 
>> on
>> first sight, THIS IS NOT OUR BUSENESS to invent/support documentation
>> format.
>
> It is my business :-). As much as I like writing libraries, I also like 
> writing tools.

I am sure you are. But Boost should use industry standard formats for it's 
documentation: html before, DocBook now. Boost can't be everything in one 
bottle: we produce c++ libraries, we don't invent documentation formats. If 
you believe you very good at it and your format is better, try to convince 
guys who actually know something about it (I mean they are experts). I am 
not the one.

> And it *is* easy to support.

It's easy now, when you've got very limited number of users. This will 
change with widespread application of this format. And to be completely 
frank with you how easy it is to support the tools for you is comparatively 
minor part of my concern. After all it's your own decision. The fact 
remains: someone need to support it. Someone need to test it. Someone need 
to documents it.

And what about these:

Do you support quickbook documents validation?
Do you plan to invent schema language?
Do you run unit tests?
How flexible is it in comparison with DocBook from extension standpoint?
Is there a single editor out there that understands this format?

> It is merely a very thin layer on top of docbook.

It's not a thin layer. This is completely different markup language. Even 
BoostBook is not thin enough IMO.

> It is very easy to understand, extend and maintain.

First of all it's subjective opinion: I personally don't like these magic 
char sequences and prefer explicit names in everything. And since you don't 
have many users yet you can't really state second and third. Let's say I 
want frames in my docs. Does quickbook is extendible to support it?

> I am not the sole maintainer. It's being maintained by some folks and
> I do get some contributions from a few more. IOTW, it's not a 
> one-man-show.

I don't believe Boost.Build, for example, is one man show as well.

> And, it is not a new toy. It's been with us since 2002.

Until someone is trying to make it de facto standard for Boost documentation 
and not just a convenience tool for HTML generation I don't care.

Did it ever go through submission process and formal review?

>>  DocBook is very mature, well supported project. It's based on widely
>> accepted/supported technologies. It's powerful and configurable to 
>> implement
>> essentially anything one need.
>
> quickbook *is* docbook. What's the worry?

What do you mean? From where I stand it's completely different format.

> If you get paranoid, you
> can just dump into xml and forget about quickbook. Nothing lost!

I am not paranoid. Above statement is pointless if I still required to 
maintain docs in this format and make no sense if I don't use it.

>> I personally don't see much valid reasons to
>> look in home grown format direction.
>
> Well, you can't please everybody ;) The good thing is, you don't need
> to use it if you don't want to.

This one is clear. The only reason for my post is to make sure the community 
is moving in right direction. Which is not IMO.

Gennadiy