bug#6175: [PATCH] dirname: tweak summary wording

[Eric Blake]

* doc/coreutils.texi (dirname invocation): Reword to be more
precise.
* src/dirname.c (usage): Likewise.
* THANKS: Update.
Reported by Filipus Klutiero, bug 6175.
---
On 05/17/2010 09:36 AM, Eric Blake wrote:
> > On 05/17/2010 09:17 AM, Filipus Klutiero wrote:
[revisiting an older thread]

>>> Strip the last component and resulting trailing slashes; if the file
>>> name contains only one component, print '.'.
>>>
>>> But I welcome your ideas for a coherent sentence.
>>>    
>> That sounds more correct and comprehensible. I don't know how many
>> corner cases there are and if they can all be covered in the help, but
>> there's also the no component case:
>> $ dirname ''
>> prints ".".
> 
> Yes, that's a corner case not covered by the above sentence, which we
> could fix with "if the file name contains less than two components,
> print '.'".

I finally had the time to look more into this bug report.  How does the
following patch sound?  The goal for the --help output is to keep things
terse at two lines, while the info page can afford the extra text for
precision.

 THANKS             |    1 +
 doc/coreutils.texi |   10 +++++++---
 src/dirname.c      |    6 +++---
 3 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/THANKS b/THANKS
index 0e1459b..dce3c94 100644
--- a/THANKS
+++ b/THANKS
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index d1c3085..26b4eba 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -11991,14 +11991,17 @@ dirname invocation
 @cindex non-directory suffix, stripping

 @command{dirname} prints all but the final slash-delimited component of
-a string (presumably a file name, but also works on directories).  Synopsis:
address@hidden  Slashes on either side of the final component are also
+removed.  If the string contains no slash, @command{dirname} prints
address@hidden (meaning the current directory).  Synopsis:

 @example
 dirname @var{name}
 @end example

-If @var{name} is a single component, @command{dirname} prints @samp{.}
-(meaning the current directory).
address@hidden need not be a file name, but if it is, this operation
+effectively lists the directory that contains the final component,
+including the case when the final component is itself a directory.

 @basenameAndDirname

@@ -12017,6 +12020,7 @@ dirname invocation
 @smallexample
 # Output "/usr/bin".
 dirname /usr/bin/sort
+dirname /usr/bin//.//

 # Output ".".
 dirname stdio.h
diff --git a/src/dirname.c b/src/dirname.c
index 4f18fe9..f6997c3 100644
--- a/src/dirname.c
+++ b/src/dirname.c
@@ -48,8 +48,8 @@ Usage: %s NAME\n\
 "),
               program_name, program_name);
       fputs (_("\
-Print NAME with its trailing /component removed; if NAME contains no /'s,\n\
-output `.' (meaning the current directory).\n\
+Print NAME with its last non-slash component and trailing slashes removed;\n\
+if NAME contains no /'s, output `.' (meaning the current directory).\n\
 \n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
@@ -57,7 +57,7 @@ output `.' (meaning the current directory).\n\
       printf (_("\
 \n\
 Examples:\n\
-  %s /usr/bin/sort  Output \"/usr/bin\".\n\
+  %s /usr/bin/      Output \"/usr\".\n\
   %s stdio.h        Output \".\".\n\
 "),
               program_name, program_name);
-- 
1.7.0.1