"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706230726t49a5b8e7k7fa5ae49bb3ae10a@mail.gmail.com...
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.
This is not exactly the same thing. Boost.Test is c++ library to be used by c++ developers. Documentation format is used by writers to write a book/article etc (in our specific case developers are writers, but this doesn't change a thing). Boost as a community (and I don't mean any particular person) should concentrate on first domain (C++ libraries development) IMO and should use existing formats for documentation writing. That doesn't mean that any one particular booster can't work on something else outside the bounds of boost.
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.
And I would object as much. Boost should use accepted standards for anything beyond our expertise.
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
You might as well claim HTML or PDF as your backend. They both well standardized and supported. That doesn't change the fact that quickbook format has nothing to do with them (as well as with DocBook one)
backend, this allow us to be sure we have a lot of support from the outside (there are tools, documentation, a community, etc).
How DocBook tools are going to help write quickbook? Does DocBook community is going to answer quickbook related questions? How reading DocBook docs helps me in any way other than confuse me?
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.
I am using XML based solution in my everyday development.
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
Well our needs and preferences are different.
2. Any change in DocBook have to be reflected in quickbook terms
IMHO this is not the idea.
Meaning? So I can't use any new feature introduced in DocBook?
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.
It still require support. And I am sure the workload will grow once it usage is widespread.
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
I am not looking for complexity. I am looking for flexibility.
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.
I believe you ;) It's still going to be there, unless you are ready to accept the responsibility of writing the documentation for everyone submitting new library.
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.
Are you going to go through formal review? Did you submit review request? How should we ask to review XSLT based solution?
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.
What I am looking for is 4 area solution(header, footer, list, concrete page)
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.
My position is that we do need to improve the documentation. But we should use recommended standards for this. Even if it means a bit more work for some people. Gennadiy