Re: document AS_BASENAME

[Ralf Wildenhues]

Hi Eric,

* Eric Blake wrote on Wed, Mar 22, 2006 at 02:35:05PM CET:
> 
> After my recent patch submission to coreutils, GNU dirname/basename will
> now return // on platforms (for now, cygwin) that have // distinct from /.
>  So the documentation needs an update; in the process, I noticed that
> AS_DIRNAME is documented but not AS_BASENAME.

Yep.  I always thought that was because `basename' is fairly portable.

> Also, do we want to remove this line about m4sh, that was picked up in the
> context of my first hunk? "For the time being, it is not mature enough to
> be widely used."

If you'd like an opinion, I'd still like a warning, maybe a bit weaker
than that.  The discussion about my pending documentation patch also
shows how immature it still is.

A small nit:

> address@hidden AS_BASENAME (@var{file-name})
> address@hidden
> +Return the filename portion of @var{file-name}, using the algorithm
> +required by Posix.  @xref{Limitations of Usual Tools}, for more

Required?  See below.

> +details about what this returns and why it is more portable than the
> address@hidden command.
> address@hidden defmac
> +
>  @defmac AS_BOURNE_COMPATIBLE
>  @asindex{BOURNE_COMPATIBLE}
>  Set up the shell to be more compatible with the Bourne shell as
>  standardized by Posix, if possible.  This may involve setting
>  environment variables, or setting options, or similar
> @@ -12156,10 +12164,35 @@ Traditional Awk @code{split} supports on
>  
>  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
> +
> +Unfortunately, neither of the above commands work if @code{$file} 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, Posix permits implementations to treat leading
> address@hidden//} with special semantics,

I sense a contradiction between "required" and "permits" here.
Are there basename implementations that turn /// into ///?
If yes, that does not get very clear here, and I think the
previous quoted comment by Paul was a bit clearer here.

>                                     but requires leading @samp{///} and
> +beyond to be equivalent to @samp{/}.  While most flavors of Unix treat
> address@hidden//} identically to @samp{/}, there are some which treat it as a
> +``super-root'' where it can provide access to other machines' files.
> +This tradition started with Apollo Domain/OS, and continues today with
> +Cygwin.
> +
> +
>  @item @command{cat}
>  @c ----------------
>  @prindex @command{cat}
>  Don't rely on any option.
>  
> @@ -12329,27 +12362,11 @@ dir=`AS_DIRNAME(["$file"])` # This is mo
>  Unfortunately, neither of the above commands work if @code{$file}'s
>  directory name ends in newline, since @address@hidden removes all
>  trailing newlines.
>  
>  @noindent
> -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
> +Similar to AS_BASENAME, AS_DIRNAME correctly handles leading @samp{//}.
>  
>  
>  @item @command{egrep}
>  @c ------------------
>  @prindex @command{egrep}