2006-03-30  Stepan Kasal  <address@hidden>

	* doc/autoconf.texi (Programming in M4sh) <AS_BASENAME>: Add an
	  example of usage.
	<AS_DIRNAME>: Likewise.
	(Limitations of Usual Tools) <basename>: Add an actual description
	  of some limitations.

Index: doc/autoconf.texi
===================================================================
RCS file: /cvsroot/autoconf/autoconf/doc/autoconf.texi,v
retrieving revision 1.972
diff -u -r1.972 autoconf.texi
--- doc/autoconf.texi	30 Mar 2006 06:42:57 -0000	1.972
+++ doc/autoconf.texi	30 Mar 2006 15:08:48 -0000
@@ -9382,9 +9382,16 @@
 @defmac AS_BASENAME (@var{file-name})
 @asindex{BASENAME}
 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
+file=/one/two/three
+file=`AS_BASENAME(["$file"])` # file is set to "three"
address@hidden example
+
address@hidden
address@hidden uses @command{basename}, if it is possible.
address@hidden of Usual Tools}, for more details about
+why it is more portable than the @command{basename} command.
 @end defmac
 
 @defmac AS_BOURNE_COMPATIBLE
@@ -9404,10 +9411,15 @@
 
 @defmac AS_DIRNAME (@var{file-name})
 @asindex{DIRNAME}
-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.
+Output the directory portion of @var{file-name}. For example,
+
address@hidden
+file=/one/two/three
+dir=`AS_DIRNAME(["$file"])` # dir is set to "/one/two".
address@hidden example
+
address@hidden
address@hidden uses @command{dirname}, if it is possible.
 @end defmac
 
 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
@@ -12178,7 +12190,8 @@
 @item @command{basename}
 @c ---------------------
 @prindex @command{basename}
-Not all hosts have a working @command{basename}, and you should instead
+Not all hosts have @command{basename} available, and some mishandle the
+corner case @samp{basename /} (e.g., Solaris), thus you should instead
 use @code{AS_BASENAME} (@pxref{Programming in M4sh}).  For example:
 
 @example
@@ -12186,6 +12199,10 @@
 file=`AS_BASENAME(["$file"])` # This is more portable.
 @end example
 
address@hidden
+Do not use @command{basename} to strip a suffix from the file name, use
address@hidden instead.
+
 
 @item @command{cat}
 @c ----------------