GNU bug report logs - #6175
dirname manpage and info page partially wrong/misleading

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 6175 in the body.
You can then email your comments to 6175 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Filipus Klutiero <chealer <at> gmail.com>
To: bug-coreutils <at> gnu.org
Subject: dirname manpage and info page partially wrong/misleading
Date: Tue, 11 May 2010 17:17:22 -0400

This report is about 2 separate issues in the dirname documentation. The 
info page is much better than the manual page, but says:
> `dirname' prints all but the final slash-delimited component of a
> string (presumably a file name, but also works on directories).
The parenthese is wrong; there is no reason to presume the file given is 
a regular file, dirname is equally useful on directories. "presumably" 
should perhaps be replaced by "usually", or removed.

The manual page is much more confusing, saying:

> DESCRIPTION
>
>
>  Print NAME with its trailing /component removed; if NAME contains no 
> /'s, output `.' (meaning the current directory).

dirname is more complex than just removing a trailing slash followed by 
a pathname component if that is the ending. For example, it also removes 
a slash followed by a pathname component followed by a slash, if that is 
how the path terminates. The manual should probably adopt the info 
page's formulation, which is more vague, but not wrong.

Message #8 received at 6175 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: Filipus Klutiero <chealer <at> gmail.com>
Cc: 6175 <at> debbugs.gnu.org
Subject: Re: bug#6175: dirname manpage and info page partially wrong/misleading
Date: Fri, 14 May 2010 17:05:01 -0600

[Message part 1 (text/plain, inline)]

On 05/11/2010 03:17 PM, Filipus Klutiero wrote:
> This report is about 2 separate issues in the dirname documentation. The
> info page is much better than the manual page, but says:
>> `dirname' prints all but the final slash-delimited component of a
>> string (presumably a file name, but also works on directories).
> The parenthese is wrong; there is no reason to presume the file given is
> a regular file, dirname is equally useful on directories. "presumably"
> should perhaps be replaced by "usually", or removed.

Thanks for the report.

Would you like to try your hand at writing this patch?  If not, I might
be able to get around to this sometime next week (I've got several
little TODO patches piled up now...)

> 
> The manual page is much more confusing, saying:

The man page is auto-generated from 'dirname --help' output; the patch
here would be to src/dirname.c, along with the matching patch to
doc/coreutils.texi.

> 
> dirname is more complex than just removing a trailing slash followed by
> a pathname component if that is the ending. For example, it also removes
> a slash followed by a pathname component followed by a slash, if that is
> how the path terminates. The manual should probably adopt the info
> page's formulation, which is more vague, but not wrong.

POSIX has a definite definition of a file name component - any sequence
that does not include a slash.  It also has definite rules for dirname
to remove the trailing component: everything that occurs after the last
slash once trailing slashes are removed (with a special case for all
slashes).  The point is that dirname removes trailing slashes, then one
component, then again removes trailing slashes.  Perhaps a more correct
formulation, while still being concise, is along these lines:

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.

-- 
Eric Blake   eblake <at> redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

[signature.asc (application/pgp-signature, attachment)]

Message #11 received at 6175 <at> debbugs.gnu.org (full text, mbox):

From: Filipus Klutiero <chealer <at> gmail.com>
To: Eric Blake <eblake <at> redhat.com>
Cc: 6175 <at> debbugs.gnu.org
Subject: Re: bug#6175: dirname manpage and info page partially wrong/misleading
Date: Mon, 17 May 2010 11:17:08 -0400

On 2010-05-14 19:05, Eric Blake wrote:
> On 05/11/2010 03:17 PM, Filipus Klutiero wrote:
>    
>> This report is about 2 separate issues in the dirname documentation. The
>> info page is much better than the manual page, but says:
>>      
>>> `dirname' prints all but the final slash-delimited component of a
>>> string (presumably a file name, but also works on directories).
>>>        
>> The parenthese is wrong; there is no reason to presume the file given is
>> a regular file, dirname is equally useful on directories. "presumably"
>> should perhaps be replaced by "usually", or removed.
>>      
> Thanks for the report.
>
> Would you like to try your hand at writing this patch?  If not, I might
> be able to get around to this sometime next week (I've got several
> little TODO patches piled up now...)
>
>    
>> The manual page is much more confusing, saying:
>>      
> The man page is auto-generated from 'dirname --help' output; the patch
> here would be to src/dirname.c, along with the matching patch to
> doc/coreutils.texi.
>    
Thanks for the direction. I would feel comfortable to write a patch, but 
I'm reluctant to spend time on making a first coreutils contribution (I 
have no intention to make more). I don't know coreutils nor POSIX that 
much. I looked at the manual page because I had no idea what dirname did 
(in fact, I was trying to understand PHP dirname's behavior). I still 
probably can't describe its behavior perfectly, so I don't mind waiting 
for someone more competent will look at it... I would probably just go 
with the info page's vague description anyway.
>    
>> dirname is more complex than just removing a trailing slash followed by
>> a pathname component if that is the ending. For example, it also removes
>> a slash followed by a pathname component followed by a slash, if that is
>> how the path terminates. The manual should probably adopt the info
>> page's formulation, which is more vague, but not wrong.
>>      
> POSIX has a definite definition of a file name component - any sequence
> that does not include a slash.  It also has definite rules for dirname
> to remove the trailing component: everything that occurs after the last
> slash once trailing slashes are removed (with a special case for all
> slashes).  The point is that dirname removes trailing slashes, then one
> component, then again removes trailing slashes.  Perhaps a more correct
> formulation, while still being concise, is along these lines:
>
> 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 ".".
$ dirname /
prints "/".

Message #14 received at 6175 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: Filipus Klutiero <chealer <at> gmail.com>
Cc: 6175 <at> debbugs.gnu.org
Subject: Re: bug#6175: dirname manpage and info page partially wrong/misleading
Date: Mon, 17 May 2010 09:36:09 -0600

[Message part 1 (text/plain, inline)]

On 05/17/2010 09:17 AM, Filipus Klutiero wrote:
>> 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 '.'".

> $ dirname /
> prints "/".

I tend to classify the all-slash corner case as being one component, not
zero components.  You can view it as the root directory being  contained
in (well, reachable from) the root directory, as evidenced by '/../'
resolving to '/'.  But that doesn't work as well with the '<2
components' wording above, so I'm feeling more comfortable with leaving
the corner-cases undocumented in the terse --help output, by using your
view that '/' has no components rather than 1, and anyone worried about
the two corner cases of '' and '/' can read the info page.

-- 
Eric Blake   eblake <at> redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

[signature.asc (application/pgp-signature, attachment)]

Message #17 received at 6175 <at> debbugs.gnu.org (full text, mbox):

From: Filipus Klutiero <chealer <at> gmail.com>
To: Eric Blake <eblake <at> redhat.com>
Cc: 6175 <at> debbugs.gnu.org
Subject: Re: bug#6175: dirname manpage and info page partially wrong/misleading
Date: Mon, 17 May 2010 15:48:22 -0400

On 2010-05-17 11:36, Eric Blake wrote:
> On 05/17/2010 09:17 AM, Filipus Klutiero wrote:
>    
>>> 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 '.'".
>
>    
>> $ dirname /
>> prints "/".
>>      
> I tend to classify the all-slash corner case as being one component, not
> zero components.  You can view it as the root directory being  contained
> in (well, reachable from) the root directory, as evidenced by '/../'
> resolving to '/'.
Hum, interesting, never thought about "/../". I believe all-slash can't 
be considered as being one component. According to POSIX, a component 
needs at least one character.
>    But that doesn't work as well with the '<2
> components' wording above, so I'm feeling more comfortable with leaving
> the corner-cases undocumented in the terse --help output, by using your
> view that '/' has no components rather than 1, and anyone worried about
> the two corner cases of '' and '/' can read the info page.
>    
Using If-s is a good idea. I would agree with leaving the no components 
case to the documentation proper. Here is a simple even though 
incomplete description based on yours. It is exact *AFAIK*. I'm using 
"pathname" instead of "file name", since file name doesn't fit the Base 
Specifications definition - but I don't know if coreutils/GNU is 
willingly using its own terminology.

If the pathname contains several components, strip the last component 
and resulting trailing slashes; if the pathname contains only one 
component, print '/' if the pathname starts with a slash, '.' otherwise.

Message #20 received at 6175 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: chealer <at> gmail.com,
	6175 <at> debbugs.gnu.org
Subject: [PATCH] dirname: tweak summary wording
Date: Mon,  7 Jun 2010 18:08:30 -0600

* 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:
+@var{name}.  Slashes on either side of the final component are also
+removed.  If the string contains no slash, @command{dirname} prints
+@samp{.} (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).
+@var{name} 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

Message #23 received at 6175 <at> debbugs.gnu.org (full text, mbox):

From: Jim Meyering <jim <at> meyering.net>
To: Eric Blake <eblake <at> redhat.com>
Cc: 6175 <at> debbugs.gnu.org, chealer <at> gmail.com
Subject: Re: bug#6175: [PATCH] dirname: tweak summary wording
Date: Tue, 08 Jun 2010 07:55:29 +0200

Eric Blake wrote:
> * doc/coreutils.texi (dirname invocation): Reword to be more
> precise.
> * src/dirname.c (usage): Likewise.
> * THANKS: Update.
> Reported by Filipus Klutiero, bug 6175.
...
> 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\

Looks fine.  I know it was there in the original too,
but s/output/print/ sounds a little better.

Message #26 received at 6175 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: Jim Meyering <jim <at> meyering.net>
Cc: 6175 <at> debbugs.gnu.org, chealer <at> gmail.com
Subject: Re: bug#6175: [PATCH] dirname: tweak summary wording
Date: Tue, 08 Jun 2010 04:32:06 -0600

[Message part 1 (text/plain, inline)]

On 06/07/2010 11:55 PM, Jim Meyering wrote:
>> -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\
> 
> Looks fine.  I know it was there in the original too,
> but s/output/print/ sounds a little better.

Pushed with that tweak.

-- 
Eric Blake   eblake <at> redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

[signature.asc (application/pgp-signature, attachment)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.