Re: [Boost-users] [spirit] how to get_position() from a multi_pass<position_iterator <const char*> >

Subject: Re: [Boost-users] [spirit] how to get_position() from a multi_pass<position_iterator <const char*> >
From: Hartmut Kaiser (hartmut.kaiser_at_[hidden])
Date: 2009-08-22 22:52:01

Edward,

> > We consider Spirit V2 to be a beta version and the docs themselves
> are not
> > complete. This will be rectified with Boost V1.41, where the docs
> will be
> > complete and Spirit V2.1 will officially replace Spirit.Classic
> (whose docs
> > will be 'hidden' from that point on).
> 
> I do not think it is wise to hide documentation when you want people to
> try a product in Beta. How is anybody supposed to find the docs when
> you
> suggest to them to try Spirit 2.0 or Spirit 2.1. Somewhere, on some web
> page centered around Spirit, you should actually have links to the 2.0
> and 2.1 docs such as they are.

The main reason for hiding those docs was that these are very incomplete. If
you compare them to the docs I pointed the OP to you'll see what I mean. 

We made sure everybody asking for Spirit V2.1 got directions on how to find
the current docs. We have had really active discussions about the beta on
the Spirit mailing list for over a year now. Many people participated. We
wrote a lot of examples and hundreds of very illustrative tests for
interested people to look at. But I agree, all this is no excuse for not
publishing the links more prominently.

> If I search for Spirit, I find a Spirit home page at
> http://spirit.sourceforge.net/, but good luck in finding 2.0 or 2.1
> docs
> from there. I can also find Spirit mentioned at the Boost home page at
> http://www.boost.org/, but again I will not find the 2.0 or 2.1 docs
> from there either.

As said, I agree we could have done a better job of advertising the newer
version. Spirit V2.1 is a huge library and we rewrote it thrice before it
actually reached the current state. Writing documentation for it is an
extremely time consuming thing (I'm working on it for 4 month daily 1-2h
now). So please excuse if we didn't find the proper amount of time to
adequately publishing what we did so far. Joel and I want to get the docs
out and will concentrate on public relations as soon as this is done.

> As far as the docs not being complete, and their eventually being
> complete when Boost 1.41 comes out, please excuse me for disagreeing
> that is the way to create Beta software. 

Sorry, I didn't get your point. What do you mean here?

> I realize how hard you and Joel
> have worked creating and updating Spirit, but I myself have just grown
> tired, after many years of programming, of implementations whose use is
> suggested but whose docs are never up to par. 

I believe the current documentation, even if not 100% complete, is
nevertheless a excellent starting point for everybody interested in Spirit.
It provides sufficient information to get started and we try to be very
responsive on the Spirit mailing list if additional questions arise. So I
think it _is_ the proper way to suggest to use the upcoming Spirit V2.1 as
it's so much better than the current official version.

> I just think is the wrong
> way to produce software, even very high quality and free software as
> Spirit is, to make programmers work harder than is necessary to
> understand how the software actually works in light of incomplete
> documentation.

If you looked at the docs I posted the link to you would have seen their
adequateness for learning about the new version. I really don't understand
what you want to say with your rant. If pre-release software is not for you,
just don't use it. We only want to avoid people start using the old Spirit
in new projects because we know the new version will be released soon.
Especially if they struggle with bugs in the old version which are already
fixed in the newer one.

> I will wait for 1.41 before I look at Spirit 2.1 to see if I might want
> to use it. 

Please be our guest!

> I do not blame the OP if he feels the same, despite your
> suggestion to hime to look at the better, more functional, later Beta
> release.

May I ask what did upset you in the first place? Did I offend you in any
way?

Regards Hartmut