"Joel de Guzman" <joel@boost-consulting.com> wrote in message news:f5j3pq$ba4$1@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