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

Previous Next

Full log

View this message in rfc822 format

From: Filipus Klutiero <chealer <at> gmail.com>
To: Eric Blake <eblake <at> redhat.com>
Cc: 6175 <at> debbugs.gnu.org
Subject: 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 "/".

Previous Next

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