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

From: Eric Blake <[email-masked]>
Date: Fri, 14 May 2010 17:05:01 -0600

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   [email-masked]    +1-801-349-2682
Libvirt virtualization library http://libvirt.org