GNU bug report logs - #12589
doc: dirname: manpage partially wrong/confusing

Message received at submit <at> debbugs.gnu.org:

Received: (at submit) by debbugs.gnu.org; 6 Oct 2012 21:31:42 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sat Oct 06 17:31:42 2012
Received: from localhost ([127.0.0.1]:58663 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1TKbyH-0007uP-O6
	for submit <at> debbugs.gnu.org; Sat, 06 Oct 2012 17:31:42 -0400
Received: from eggs.gnu.org ([208.118.235.92]:52891)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <chealer@HIDDEN>) id 1TKbyF-0007uC-HT
	for submit <at> debbugs.gnu.org; Sat, 06 Oct 2012 17:31:41 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <chealer@HIDDEN>) id 1TKbxr-0008Cz-9j
	for submit <at> debbugs.gnu.org; Sat, 06 Oct 2012 17:31:16 -0400
X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org
X-Spam-Level: 
X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00,FREEMAIL_FROM,
	RCVD_IN_DNSWL_HI,T_DKIM_INVALID autolearn=unavailable version=3.3.2
Received: from lists.gnu.org ([208.118.235.17]:57106)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <chealer@HIDDEN>) id 1TKbxr-0008Cv-6M
	for submit <at> debbugs.gnu.org; Sat, 06 Oct 2012 17:31:15 -0400
Received: from eggs.gnu.org ([208.118.235.92]:43073)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <chealer@HIDDEN>) id 1TKbxq-000851-42
	for bug-coreutils@HIDDEN; Sat, 06 Oct 2012 17:31:15 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <chealer@HIDDEN>) id 1TKbxo-0008Ch-U5
	for bug-coreutils@HIDDEN; Sat, 06 Oct 2012 17:31:14 -0400
Received: from mail-qa0-f48.google.com ([209.85.216.48]:42024)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <chealer@HIDDEN>) id 1TKbxo-0008Ca-Po
	for bug-coreutils@HIDDEN; Sat, 06 Oct 2012 17:31:12 -0400
Received: by mail-qa0-f48.google.com with SMTP id c11so1443749qad.0
	for <bug-coreutils@HIDDEN>; Sat, 06 Oct 2012 14:31:10 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113;
	h=message-id:date:from:user-agent:mime-version:to:subject
	:content-type:content-transfer-encoding;
	bh=/aqKrng2kAC6l+OSXe7X1iZwb4fDQciI2jEBtXI7iVs=;
	b=HdIj3B4pAc+k77m2Hd7qnI/oMP6BCgWclHu6Cv5bA2bP1Dp/SByniPsG8BcFXHEaiT
	9+2JFx4kIiwtW5/6iWFK70+676e4qOBhOMtBQ4/aN6yXZafegVsWDQ6MsGlhaBEx1QY5
	a11SOIFrv/zo0/85H7chVGZ6+UBSpykNwhZdlvnS1lbs7AGdji4zwV0Z95o2wK9L1CI/
	cFrN+jk4rVY/Wecje0AF7a1yyhsEYnzkfEZae3DkrlFAvLr8nCaPULwh/rWjMebFCgrB
	FoNolwuFbbe92/MhnbRXx4WOA5NnPzD5RTuKo/h7VMBJUtlfLoNNiFh2XK+9fy2aLBFS
	wPag==
Received: by 10.229.136.7 with SMTP id p7mr5194072qct.102.1349559070311;
	Sat, 06 Oct 2012 14:31:10 -0700 (PDT)
Received: from [192.168.1.9] (modemcable156.191-56-74.mc.videotron.ca.
	[74.56.191.156])
	by mx.google.com with ESMTPS id o17sm13632194qao.14.2012.10.06.14.31.08
	(version=SSLv3 cipher=OTHER); Sat, 06 Oct 2012 14:31:09 -0700 (PDT)
Message-ID: <5070A30C.5060603@HIDDEN>
Date: Sat, 06 Oct 2012 17:30:52 -0400
From: Filipus Klutiero <chealer@HIDDEN>
User-Agent: Mozilla/5.0 (X11; Linux i686 on x86_64;
	rv:10.0.7) Gecko/20120922 Icedove/10.0.7
MIME-Version: 1.0
To: bug-coreutils@HIDDEN
Subject: dirname manpage partially wrong/confusing
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: Genre and OS details not
	recognized.
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3)
X-Received-From: 208.118.235.17
X-Spam-Score: -3.4 (---)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.13
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <http://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <http://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <http://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
	<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Sender: debbugs-submit-bounces <at> debbugs.gnu.org
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
X-Spam-Score: -3.4 (---)

This report follows a previous report about dirname's info page and 
manpage: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=6175

dirname's info page is now IMO correct and quite clear in its 
description of dirname's behavior:

>  `dirname' prints all but the final slash-delimited component of NAME.
>  Slashes on either side of the final component are also removed.  If the
>  string contains no slash, `dirname' prints `.' (meaning the current
>  directory).

However, the manpage is still confusing. It used to read:

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

It now reads:

> Output NAME with its last non-slash component and trailing slashes removed; if NAME contains no /'s, output `.' (meaning the current directory).

First, it's unclear what kind of component this refers to. A slash is 
not a pathname component, therefore "non-slash component" would seem 
equivalent to simply "component". If one understands "component" as 
pathname component, then the description becomes equivalent for the 
typical case of "/foo/bar" to:

 > Output "/foo/bar" with its last component and trailing slashes removed.

That would, in my understanding, mean outputting "/foo/" (there are no 
trailing slashes in "/foo/bar"). But dirname would actually output 
"/foo", removing the last slash in the result.

I would recommend adopting the same description as the one used in the 
info page.

By the way, the short description reads:
> strip last component from file name

In POSIX terminology, this sounds like "take a filename, output 
nothing". "from a pathname" would make more sense.