bug#6175: dirname manpage and info page partially wrong/misleading

[Filipus Klutiero]

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 "/".