On 6/23/07, Gennadiy Rozental <gennadiy.rozental@thomson.com> 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.
100% Agree with you. I have spend last two weeks learning Docbook, his history and where it is heading and I have to said I am really impressed too. Docbook 5 will rock, they are starting to use RelaxNG instead of DTD and will apply all the power of xsl 2. We should be really happy to have such an amazing and supported project as our backend.
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.
Ok, thanks for taking the time to comment on it.
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.
As Joel said it is *my* business too. And IMHO you are too. We could use a different thing than Boost.Test, but I am very happy with it and I really appreciate such a wonderful project is maintained by a boost developer.
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. I personally don't see much valid reasons to look in home grown format direction.
First of all. I will be proposing to use Quickbook even if it is not inside Boost. I really think that Quickbook (plus the necessary backend) is a hell of a documenting tool and IMHO in the future other projects will start to using it (Yesterday I spend part of the day working on a boost agnostic version of boostbook to better support outsiders) Also there is a big difference between our homegrown build system. As Joel state it we are proposing dockbook as our documentation format backend, this allow us to be sure we have a lot of support from the outside (there are tools, documentation, a community, etc). Quickbook and boostbook is very small (but yet powerful) layer that IMHO works better for us. If you want to write in docbook, it is ok. I really think you will change your opinion when you use both tools for a while. You can not make strong statements without trying them.
Here some specific points:
1. Simplicity Some people argues that it's easier to type quickbook I might argue that it's actually opposite. Granted if you use vi XML editing is not fun. But myriads of modern XML editors simplify the process marginally. There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow. In addition you get immediate format validation and presentation (using assigned stylesheets)
I have use these tools and they are very good indeed. The same thing happens to latex, the LyX project allows you to write almost WYSWYG and it is a handy tool to know but if you asked around, almost everybody will tell you that they prefer and are far more productive writing directly in latex. It is the same with Quickbook, once you use it for a while you will be very productive and happy as is. The only aid I need is something like this: http://tinyurl.com/2ll5tk
2. Any change in DocBook have to be reflected in quickbook terms
IMHO this is not the idea.
3. Someone need to maintain quickbook parser/transformer
There are a lot of people interested in maintained it and we have Joel with us ;) I am really interested in offer my help to maintain the boost docs tools.
4. quickbook will never be as flexible as DocBook
We are not looking for more flexibility, we are aiming at simplicity. If you need the extra complexity just write docbook, it is compatible with the current efforts. But please first tell us what have you fail to do in quickbook, it may be that you just do not have enough experience with it. Moreover... quickbook templates rocks and in the feature quickbook will be even thinner.
5. This is new *nonstandard* format any new developer will have to learn. I don't believe we can afford yet another barrier for new submitters.
Believe me that I am working very hard to low the barrier.
II. BoostBook
1. Complexity The BoostBook being an extension to DocBook seems to be doing too much. IMO any useful generic innovations should be proposed to the DocBook developers and eventually removed. All in all we should strive to make this layer as thin as possible.
Docbook is a very slow changing project. It has to be. I have been hacking boostbook internals for the last two weeks. I have simplify a lot of things. I am currently working on documentation. I hope to have it ready soon.
2. Test suites support. I did not really grasp the idea behind this feature completely, but from what I understand this is "misfeature" and should be removed
I have never used it, no strong opinion here.
3. Tight coupling with Boost.Build This is major problem I believe. Especially in documentation. BoostBook should be presented as independent project. It should be explained how to use it, configure it without any reference to Boost.Build at all. At the very last chapter of documentation we may refer that if you want you docs to be automatically generated on some remote host (if let's say you don't have all the tools set up locally for all the formats) this is what you need to do .....
I am working to make boostbook a boost agnostic tool.
4. Documentation I found documentation to be largely unacceptable (funny thing for the project dedicated to writing documentation)
a) No explanation how to use BoostBook without Boost.Build (see above)
Good point, I will add a page about this.
c) most critical: no description whatsoever of all the modification done in comparison with DocBook. All the updated parameter need to be listed, all the updated templates need to be explained. General approach should be what the person familiar with DocBook (standard) need to know/expect to use BoostBook
I spend a big part of yesterday doing this :) Just give me a few more hours to polish it.
d) No explanation on how to extend the BoostBook (especially in comparison with DocBook)
Ok, this may be a good thing to add in the future. It is not a priority now.
As I mentioned before we should try to limit our extensions to the most necessary only and strive to stick with standard DocBook. Also all extensions should be made optional.
All extensions are optional, input a docbook source to boostbook and it will work.
III. What should we do?
IMO the standardization efforts need to target DocBook/BoostBook. On the other hand each developer should be allowed to extend/twick standard L&F. Usually differences should be only cosmetic.
This is exactly what we are doing. I think that is fair to say that I spend last two weeks in: 40% boostbook 20% css 15% sending mails to boost-docs 10% javascript 10% learning 5% quickbook (no sleep :P)
Following are general observations about common L&F
1. JS Menu support. I believe it should be implemented but made optional. I personally don't like it (I believe it's just wait of space for this menu to stay on all the time) and prefer "location path" kinda navigation Boost.Test currently using.
It is optional.
2. Header on top. I don't believe it's necessary. Neither in a form of boost|libraries|more|... nor what is currently proposed. This information is accessible from boost main page. No need to duplicate it on every page of every library.
They are optional (I have work on this yesterday)
3. Frames I personally need frames support for the reference like pages (like in preprocessor and test libraries). I am open to the alternative that presents similar L&F.
Frames are bad friend of the new web. They are not embrace by standards. I am working in an optional sidebar that will let you do the same.
4. Portability This is major requirement for all the features we implement. They should work on at least set of predefined "major" browsers.
Have you seen this: http://svn.boost.org/trac/boost/wiki/BrowserTestingChart
Please make this as discouraging comments to overall documentation efforts movements. I just don't believe we move in right direction.
I hope we can work together to move things in the right direction. IMO your direction is a lot more similar from the current "Improving Boost Docs" project that you think. Regards Matias