Re: document AS_BASENAME

[Paul Eggert]

Thanks for suggesting that.  I installed the following
more-streamlined edition of your patch.

2006-03-29  Paul Eggert  <address@hidden>

        * doc/autoconf.texi (Programming in M4sh): Mention AS_BASENAME.
        Give an example for AS_DIRNAME instead of referring to Posix..
        (File System Conventions): Put discussion of // versus / here, and
        modernize it a bit.
        (Limitations of Usual Tools): Add basename.  Remove verbiage
        after dirname, since it got moved to the above sections.
        All this was inspired by a patch proposed earlier by Eric Blake.

--- doc/autoconf.texi   21 Mar 2006 21:51:07 -0000      1.971
+++ doc/autoconf.texi   30 Mar 2006 06:42:57 -0000      1.972
@@ -9379,6 +9379,14 @@ For the time being, it is not mature eno
 M4sh provides portable alternatives for some common shell constructs
 that unfortunately are not portable in practice.
 
address@hidden AS_BASENAME (@var{file-name})
address@hidden
+Output the non-directory portion of @var{file-name}.  For example,
address@hidden([/one/two/three])} outputs @samp{three}.
address@hidden of Usual Tools}, for more details about what this
+returns and why it is more portable than the @command{basename} command.
address@hidden defmac
+
 @defmac AS_BOURNE_COMPATIBLE
 @asindex{BOURNE_COMPATIBLE}
 Set up the shell to be more compatible with the Bourne shell as
@@ -9396,10 +9404,10 @@ corresponding pattern matched @var{word}
 
 @defmac AS_DIRNAME (@var{file-name})
 @asindex{DIRNAME}
-Return the directory portion of @var{file-name}, using the algorithm
-required by Posix.  @xref{Limitations of Usual Tools}, for more
-details about what this returns and why it is more portable than the
address@hidden command.
+Output the directory portion of @var{file-name}.  For example,
address@hidden([/one/two/three])} outputs @samp{/one/two}.
address@hidden of Usual Tools}, for more details about what this
+returns and why it is more portable than the @command{dirname} command.
 @end defmac
 
 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
@@ -10570,6 +10578,14 @@ violations to the above restrictions.
 On some Posix-like platforms, @samp{!} and @samp{^} are special too, so
 they should be avoided.
 
+Posix lets implementations treat leading @file{//} specially, but
+requires leading @file{///} and beyond to be equivalent to @file{/}.
+Most Unix variants treat @file{//} like @file{/}.  However, some treat
address@hidden//} as a ``super-root'' that can provide access to files that are
+not otherwise reachable from @file{/}.  The super-root tradition began
+with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin
+has revived it.
+
 While @command{autoconf} and friends will usually be run on some Posix
 variety, it can and will be used on other systems, most notably @acronym{DOS}
 variants.  This impacts several assumptions regarding file names.
@@ -12158,6 +12174,19 @@ Traditional Awk has a limit of 99
 fields in a record.  You may be able to circumvent this problem by using
 @code{split}.
 
+
address@hidden @command{basename}
address@hidden ---------------------
address@hidden @command{basename}
+Not all hosts have a working @command{basename}, and you should instead
+use @code{AS_BASENAME} (@pxref{Programming in M4sh}).  For example:
+
address@hidden
+file=`basename "$file"`       # This is not portable.
+file=`AS_BASENAME(["$file"])` # This is more portable.
address@hidden example
+
+
 @item @command{cat}
 @c ----------------
 @prindex @command{cat}
@@ -12326,29 +12355,6 @@ dir=`dirname "$file"`       # This is no
 dir=`AS_DIRNAME(["$file"])` # This is more portable.
 @end example
 
-Unfortunately, neither of the above commands work if @code{$file}'s
-directory name ends in newline, since @address@hidden removes all
-trailing newlines.
-
address@hidden
-This handles a few subtleties in the standard way required by
-Posix.  For example, under UN*X, should @samp{dirname //1} give
address@hidden/}?  Paul Eggert answers:
-
address@hidden
-No, under some older flavors of Unix, leading @samp{//} is a special
-file name: it refers to a ``super-root'' and is used to access other
-machines' files.  Leading @samp{///}, @samp{////}, etc.@: are equivalent
-to @samp{/}; but leading @samp{//} is special.  This tradition
-started with Apollo Domain/OS, though it has largely died out in practice.
-
-Posix allows but does not require the special treatment for
address@hidden//}.  It says that the behavior of @command{dirname} on file 
names of the
-form @samp{//([^/]+/*)?} is implementation defined.  In these cases,
address@hidden @command{dirname} returns @samp{/}, but those no-longer-used
-flavors of Unix returned @samp{//}.
address@hidden quotation
-
 
 @item @command{egrep}
 @c ------------------