Re: [boost] Boost documentation

From: Matias Capeletto (matias.capeletto_at_[hidden])
Date: 2007-06-23 10:26:54

On 6/23/07, Gennadiy Rozental <gennadiy.rozental_at_[hidden]> 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