(basename invocation, dirname invocation):

Improve documentation to match recent // patches.

1 files changed, 21 insertions, 2 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 094fbd422..b192984b6 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -10588,8 +10588,25 @@ basename @var{name} [@var{suffix}]
 @end example
 
 If @var{suffix} is specified and is identical to the end of @var{name},
-it is removed from @var{name} as well.  @command{basename} prints the
-result on standard output.
+it is removed from @var{name} as well.  Note that since trailing slashes
+are removed prior to suffix matching, @var{suffix} will do nothing if it
+contains slashes.  @command{basename} prints the result on standard
+output.
+
+@c This test is used both here and in the section on dirname.
+@macro basenameAndDirname
+Together, @command{basename} and @command{dirname} are designed such
+that if @samp{ls "$name"} succeeds, then the command sequence @samp{cd
+"$(dirname "$name")"; ls "$(basename "$name")"} will, too.  This works
+for everything except file names containing a trailing newline.
+
+@acronym{POSIX} allows the implementation to define the results if
+@var{name} is empty or @samp{//}.  In the former case, @acronym{GNU}
+@command{basename} returns the empty string.  In the latter case, the
+result is @samp{//} on platforms where @var{//} is distinct from
+@var{/}, and @samp{/} on platforms where there is no difference.
+@end macro
+@basenameAndDirname
 
 The only options are @option{--help} and @option{--version}.  @xref{Common
 options}.  Options must precede operands.
@@ -10625,6 +10642,8 @@ dirname @var{name}
 If @var{name} is a single component, @command{dirname} prints @samp{.}
 (meaning the current directory).
 
+@basenameAndDirname
+
 The only options are @option{--help} and @option{--version}.  @xref{Common
 options}.