Understanding alias (used as rewrite)

[E.B.]

> >> This config works for me.
> >>
> >>   location ~ ^/test {
> >>     alias /data/public_html/somefile.php;
> >>
> >>     include fastcgi.conf;
> >>
> >>     fastcgi_pass 127.0.0.1:8900;
> >>   }
> >
> > Yes, I had also got similar to work, but
> > only for the exact match uri-- the first
> > in my list of possible uris that must work:
> >
> > /my-long-prefix-goes-here
> > /my-long-prefix-goes-herexxx
> > /my-long-prefix-goes-here/
> > /my-long-prefix-goes-here/filename
> >
> > I still get 404 for the last 3. That's why
> > I thinking it was adding the end of the original
> > uri to the alias redirect. but Im not sure.
>
> you need the regexp-based alias (as in my example).

Well, in the very next sentence I told you I
already tried your regex version with no luck.

But with some helpful explaining from you
and Francis I understand better and also
found a bug. Next mail for more.

> it depends on the type of locaton. If it's regexp-based alias
> (location ~ ^/some/(regexp)), the full path is replaced with whatever
> in alias params but otherwise the trailing request uri (the one after
> path specified in location) will be appended to the alias.

OK. It wasn't working that way for me but 
I discovered cuz of a config bug. So now
I understand this but WHY ISNT THIS DOCUMENTED?