Re: [boost] [spirit] New Header Structure [was Re: Proposal: Add Loki Library's SafeFormat to Boost:]

Subject: Re: [boost] [spirit] New Header Structure [was Re: Proposal: Add Loki Library's SafeFormat to Boost:]
From: Markus Werle (numerical.simulation_at_[hidden])
Date: 2009-01-09 16:36:35

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.

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.

I read with great interest about how many people get confused
about what has happened to spirit in the last few releases.
Therefore I really think that we have a problem here, 
even - yes! - even if we cannot write a ticket about it or
write a minimal cpp file. I'll give it another try below,
because maybe I am wrong and then this should be clarified
once for all times.

> What you are saying is not what Robert is saying. 
> Robert says that the solution is flawed. 

I *thought* we aim into the same direction, namely *not* to
do the /classic/ header magic. 

> You say it is perfect but disliked. 

The result is the same: Spirit-2 and Spirit-1 should 
not be in the same directory.

> Did you lose context here? 

I hope not. But I am unsure, of course.
We were talking about issues with Spirit-1 vs. Spirit-2?

> Is what you are saying related to 
> the new header structure at all? What "header magic" is it
> you are talking about? Header forwarding is not magic at all.
> People do it all the time. 

So here I try again.
I see 3 main issues with the new spirit:

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.
OK, so Spirit-2b is a first class citizen and the preferred 
version to use? 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
when I #include <boost/spirit.hpp>. So I felt uncomfortable.

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.
Sigh. That's really uncool. Really. It made me *feel* something was
broken here, even if it is not.

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,
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 
(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.

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?

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. 

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,
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

> I'm confused. More confused than ever. 
> If it is the new features and names you are 
> complaining about, then this is the wrong thread. 

No, not complaining here.

> This thread is about Robert's assertion that 
> the new header structure causes breakage. 

I think even in the absence of a minimal.cpp or
other proof we should believe Robert who said
that he had some trouble. He described it earlier
in this thread.
Would be nice to fix that using minimal.cpp, 
but 

if (!show_proof())
{
        no_problem_exists();
}
else
{
        fix_code();
}

is not the perfect code.
I prefer:

if (true)
{
        separate_the_two_libraries();
}

Markus