Re: [boost] Boost documentation

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

"Matias Capeletto" <matias.capeletto_at_[hidden]> wrote in message 
news:e9b043a10706230726t49a5b8e7k7fa5ae49bb3ae10a_at_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