Boost logo

Boost :

Subject: Re: [boost] [spirit] New Header Structure [was Re: Proposal: Add Loki Library's SafeFormat to Boost:]
From: Joel de Guzman (joel_at_[hidden])
Date: 2009-01-09 20:37:08


Markus Werle wrote:
> Joel de Guzman wrote:
>
>> Markus Werle wrote:
>
>>> I drop into this discussion here because for
>>> future changes of the boost library I'd like to see
>>> some rules established that disallow such header magic
>>> for well-established, mature parts of boost.
>> Oh man! Here I go again: If you have some problems, please do
>> as a we normally do: post a minimal cpp file that exhibits
>> the problem. Better yet, submit a trac ticket. Otherwise,
>> I can never every know what the problem really is.
>
> First of all: I am sorry to add to your frustration here.
> You did not deserve this, since the work you do for us all
> outweighs *any* pain we might have with one of your libraries.
> So I am in a beggars position anyway.

No apologies needed. This thread you replied to was intended
to clarify one point: Robert's statement that the new header
structure causes breakage. I think the confusion is that so
many issues are bundled together into one. That is why I renamed
the title of this thread to focus on only that specific issue:

1) I said we want 100% backward compatibility while at the same
    time usher in the new generation.
2) Robert says it was a "failure" and gave a narative of the
    events leading to his conclusion that the include strategy
    causes code breakage, hence, not 100% backward compatible.
3) I asked for a minimal cpp file that exhibits the problem.

> All I am trying to do is give you the feedback about some
> issues about decisions which were made to ease user's
> life, but probably do not always completely reach this goal
> as expected.

Fair enough. I'll try to reply to each of your points below.
It's unfortunate that the focus is lost again, but, anyway...

> 1. A lot of Confusion is due to some _minor_ potential for
> improvement in the docs.
>
> 2. Spirit-2b is a break-all-of-the-interface-change.
> Merging it with the old Spirit was the wrong decision.
>
> Here are some details:
>
> 1. I was mislead by the directory structure of spirit:
>
> When I had obtained the new boost version I directly went to
> libs/spirit/index.html and found the Spirit-2b docs.

See my other post too. No, that is wrong.
BOOST_ROOT/libs/spirit/index.html still (as of 1.37) points to
the classic documents. You must be confusing it with the one
in the trunk.

> OK, so Spirit-2b is a first class citizen and the preferred
> version to use?

No. Not at this point.

> No, I got it wrong. From the ML I learned
> you had taken measures to make migration as smooth as possible.
>
> Also I found:
> <cite thread="[spirit2] Documentation?">
>> http://www.boost.org/libs/spirit/doc/html/index.html
>
> [Joel writes:]
> Caveat: It's a work in progress. I hope we can finally find the time
> to complete the docs.
> </cite>
>
> I really do not understand, why the beta version of the
> library Spirit-2b has its beta docs at the *standard* place
> libs/spirit/index.html while Spirit-1 is what I get

Check the Boost 1.37 again, please. The *standard* place
libs/spirit/index.html *HAS* spirit-1.

> when I #include <boost/spirit.hpp>. So I felt uncomfortable.

Which also has Spirit1.

> More uncertainity when you come from
> http://www.boost.org/doc/libs/1_37_0: Now you are pointed to
> http://www.boost.org/doc/libs/1_37_0/libs/spirit/classic/index.html.

Again, Spirit1.

> Sigh. That's really uncool. Really. It made me *feel* something was
> broken here, even if it is not.

Agreed.

> Confusion also due to this: The place of the Spirit-2b docs indicates
> to me that Spirit-2b is the preferred library to use from now on,

No. It is not.

> but at the same time you write in the ML that there are performance
> issues and that the docs are incomplete. Also Spirit-1 still is the
> first class citizen regarding the header files.
>
> I think most *confusion* can be erased if
> libs/spirit/index.html had some explanatory text

That is a good idea, but that is not the case. As far as the release
is concerned. Perhaps we can do that for the trunk to avoid further
confusion.

> (copy'n'paste from all of your many many postings
> and include portions of the change log)
> about what is what and which version is where, just in order
> to help people decide which version of spirit to use and
> HOW to use it.

Sure. Ok.

> Also 1_37_0/libs/spirit/classic/change_log.html says
> "For more details about this change please consult the documentation."
> But which documentation is meant? The new one? The old one?
> Any links?

Ok.

> 2. Spirit-2b is a break-all-of-the-interface-change.
> I understand that some people prefer it to be in
> directory spirit2 and you prefer it to be merged
> with spirit-1. I respect your opinion and your freedom
> but I strongly disagree.

Right now, a developer can update/enhance/improve his library anyway
he sees fit without further review. If you or anyone else want to
change the rules, work on it actively. Writing a draft proposal
is a good first step. I'll abide by the rules when we have them.
For now, we don't have such a rule.

> Since Spirit-1 is very important, I am happy to hear
> it will stay in boost for a looong time.
> I have so much code depending on spirit-1
> I cannot afford a removal of spirit-1 from boost.
>
> I am not the only one.
> So you cannot deprecate the usage of Spirit-1,

Spirit-1 is *NOT* deprecated. Only the old headers are
deprecated.

> due to so many people using it around the world.
> Spirit-1 and Spirit-2 must stay inside the boost distro
> side-by-side. This is the key point.
>
> Where we disagree is the semantics of side-by-side.
> IMHO spirit/home/classic/* and spirit/* are not side-by-side.
> IMHO spirit/ and spirit2/ is truly side-by-side.
>
> You wrote a new library. It retakes the ideas of spirit-1.
> It uses completely different concepts. It is based on
> new cool stuff like fusion/proto/etc. .
> It has a completely different interface.
> It introduces many many new features and functionality.
>
> For me this library (which you call Spirit-2) is
> something so fundamentally new, it should
> a) undergo some review (at least concerning the interface)
> b) reside in its own directory

Again, if you want to see the rules changed. Work on it.
Advocacy is good. You can start with a formal proposal for
discussion.

Regards,

-- 
Joel de Guzman
http://www.boostpro.com
http://spirit.sf.net

Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk