[PATCH RC2] File::Spec::Unix::splitpath() doc.

Steven Knight wrote, in part:
> 
> I've cc'ed Barrie Slaymaker on this reply, as he's taken over maintenance
> of File::Spec.

Not really--it's in the tender hands of perl5-porters.  I'm just a
contributor to it.  And the cause of Johan's confusion, apparently :-/

> On Thu, 16 Mar 2000, Johan Holmberg wrote:
>
> > I agree that a common interface for manipulation of
> > filenames/paths on different platforms is a good thing.
> >
> > But, I must say I'm a bit disappointed by File::Spec. The
> > documentation is rather poor, and the *sematics* of
> > the different functions are not very well described.

Very true & mea culpa, partly.  If you can dig in and make them 
better, patches may be sent to perl5-porters@perl.org [CCed].  If not, 
even just sending questions or suggestioned documentation there.  A really
good pass at the documentation including a tutorial section in Spec.pm's
POD would be a major improvement.

> > One example (from File::Spec::Unix):
> > >
> > >       File::Spec->splitdir( "/a/b/c" );
> > >
> > >   Yields:
> > >
> > >       ( '', 'a', 'b', '', 'c', '' )
> > >
> >
> > This is wrong. When I try it I get:
> >
> >         ( '', 'a', 'b', 'c' )
> 
> You're correct, this example is wrong.  I had the same confusion when
> I was trying to figure out how to use File::Spec, and almost decided to
> *not* use File::Spec because of this!  I couldn't understand the example,
> and thought that maybe that meant I wasn't using an appropriate package...

Eeek--this was my bad from the getgo.  Sorry about that.

> I already brought this to Barrie's attention, and believe he's fixed
> the documentation in the latest versions.

I should have... patch below.

> > Another example: If I execute the following:
> >
> >     $path = "/a/b/c";
> >     ($volume,$dirs,$name) = File::Spec->splitpath($path);
> >
> >     @dirs1 = File::Spec->splitdir($dirs);
> >     print "dirs1: ",join(", ", map("'$_'",@dirs1)),"\n";
> >
> >     @dirs2 = File::Spec->splitdir(File::Spec->catdir(@dirs1));
> >     print "dirs2: ",join(", ", map("'$_'",@dirs2)),"\n";
> >
> > I get this output:
> >
> >     dirs1: '', 'a', 'b', ''
> >     dirs2: '', 'a', 'b'
> >
> > Why are these different ?

catdir() calls canonpath() which removes the trailing '/' on Unix.

> > Why the trailing empty component in the first case ?
> > Why doesn't splitpath remove the trailing / on the directory component ?

I think these are the same question asked two ways.

splitpath() returns ( '', '/a/b/', 'c' ).  The main reason for the trailing
'/' is not to throw information away.  Even though the trailing '/' is not 
necessary, it can be nice to have as a marker of dir-ness.  OTOH, consistency
may be the better part of valor here, and having $dirs[-1] be the last name
is compelling.

> > To me this seems very weird.
> > Without information about the intended sematics, I'm almost
> > totally lost ...
> >
> > I ask you about this because I got the impression from the cons-list
> > that you "liked" File::Spec. Maybe I should direct my questions
> > elsewere, but I'm also interested in your view about these things.
> 
> I agree with you that File::Spec needs some better documentation about
> its semantics--that would probably help clear up a lot of confusion,
> and would have saved time when I started trying to use.
> 
> I've adopted File::Spec largely because that's very clearly the direction
> that Perl is heading--if you read through the perl5-porters mailing
> list, everyone is recommending that file name manipulation be done
> using File::Spec.  It's still young, and needs work

It's not that young, it grew out of some older code in Make::Maker.
But it's seeing wider use now and feeping creaturism, for which I
must take some of the blame :-).

> 
> I've found Barrie to be extremely helpful and cooperative, 

Rats, gotta work harder on being unresponsive.  Thanks :-).

> so if you are
> able to contribute something (documentation fixes, etc.), I'm sure he'd
> be receptive.

More importantly, perl5-porters would be very receptive.

- Barrie

---------------------------8<-------------------------
--- perl-5.6.0-RC2/lib/File/Spec/Unix.pm	Thu Mar  2 21:54:21 2000
+++ File-Spec/lib/File/Spec/Unix.pm	Thu Mar 16 13:49:27 2000
@@ -242,11 +242,13 @@
 that have the concept of a volume or that have path syntax that differentiates
 files from directories.

-Unlike just splitting the directories on the separator, leading empty and 
-trailing directory entries can be returned, because these are significant
-on some OSs. So,
+Unlike just splitting the directories on the separator, empty
+directory names (C<''>) can be returned, because these are significant
+on some OSs (e.g. MacOS).

-    File::Spec->splitdir( "/a/b/c" );
+On Unix,
+
+    File::Spec->splitdir( "/a/b//c/" );

 Yields:

• [PATCH RC2] File::Spec::Unix::splitpath() doc. by Barrie Slaymaker