GNU bug report logs -
#6175
dirname manpage and info page partially wrong/misleading
Previous Next
Full log
Message #11 received at 6175 <at> debbugs.gnu.org (full text, mbox):
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 "/".
This bug report was last modified 14 years and 42 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.