From 855dbdadbf75ca1f08f3e1c7c6811670e952d906 Mon Sep 17 00:00:00 2001
From: James Youngman <jay@gnu.org>
Date: Sun, 1 Sep 2019 14:55:57 +0100
Subject: [PATCH] find: Clarify description of %f and %h.
To: findutils-patches@gnu.org

Fix https://savannah.gnu.org/bugs/index.php?35253
* doc/find.texi (Name Directives): Clarify description of %f and %h.
* find/find.1 (-printf): Likewise.
* NEWS: mention this change.
---
 NEWS          |  2 ++
 doc/find.texi | 29 +++++++++++++++++++++++------
 find/find.1   | 40 ++++++++++++++++++++++++++++++++++++----
 3 files changed, 61 insertions(+), 10 deletions(-)

diff --git a/NEWS b/NEWS
index 74cf772d..cb84fafd 100644
--- a/NEWS
+++ b/NEWS
@@ -8,6 +8,8 @@ GNU findutils NEWS - User visible changes.      -*- outline -*- (allout)
 
 #48135: Fix testsuite error on Hurd and BSD related to ln
 
+#35253: Clarify descriptions of -printf %f, %h.
+
 * Major changes in release 4.7.0, 2019-08-29
 
 ** Changes to locate / updatedb
diff --git a/doc/find.texi b/doc/find.texi
index d48d178e..fbfa57ef 100644
--- a/doc/find.texi
+++ b/doc/find.texi
@@ -1837,15 +1837,15 @@ it was encountered by @code{find} - that is, as a relative path from
 one of the starting points).
 @item %f
 File's name with any leading directories removed (only the last
-element).
+element).  That is, the basename of the file.
 @c supports %-X.Yf
 @item %h
 Leading directories of file's name (all but the last element and the
-slash before it).  If the file's name contains no slashes (for example
-because it was named on the command line and is in the current working
-directory), then ``%h'' expands to ``.''.  This prevents ``%h/%f''
-expanding to ``/foo'', which would be surprising and probably not
-desirable.
+slash before it).  That is, the dirname of the file.  If the file's
+name contains no slashes (for example because it was named on the
+command line and is in the current working directory), then ``%h''
+expands to ``.''.  This prevents ``%h/%f'' expanding to ``/foo'',
+which would be surprising and probably not desirable.
 @c supports %-X.Yh
 @item %P
 File's name with the name of the command line argument under which
@@ -1856,6 +1856,23 @@ Command line argument under which file was found.
 @c supports %-X.YH
 @end table
 
+For some corner-cases, the interpretation of the @samp{%f} and
+@samp{%h} format directives is not obvious.  Here is an eample
+including some output:
+
+@example
+$ find \
+  . .. / /tmp /tmp/TRACE compile compile/64/tests/find \
+  -maxdepth 0 -printf '%p: [%h][%f]\n'
+.: [.][.]
+..: [.][..]
+/: [][/]
+/tmp: [][tmp]
+/tmp/TRACE: [/tmp][TRACE]
+compile: [.][compile]
+compile/64/tests/find: [compile/64/tests][find]
+@end example
+
 @node Ownership Directives
 @subsubsection Ownership Directives
 
diff --git a/find/find.1 b/find/find.1
index 38e8518c..91c0c85e 100644
--- a/find/find.1
+++ b/find/find.1
@@ -1489,7 +1489,15 @@ File's depth in the directory tree; 0 means the file is a starting-point.
 The device number on which the file exists (the st_dev field of struct
 stat), in decimal.
 .IP %f
-File's name with any leading directories removed (only the last element).
+Print the basename; the file's name with any leading directories
+removed (only the last element).  For
+.BR /,
+the result is
+.BR /.
+See the
+.B EXAMPLES
+section for an example.
+
 .IP %F
 Type of the filesystem the file is on; this value can be used for
 \-fstype.
@@ -1498,9 +1506,14 @@ File's group name, or numeric group ID if the group has no name.
 .IP %G
 File's numeric group ID.
 .IP %h
-Leading directories of file's name (all but the last element).
-If the file name contains no slashes (since it is in the current
-directory) the %h specifier expands to `.'.
+Dirname; the Leading directories of the file's name (all but the last
+element).  If the file name contains no slashes (since it is in the
+current directory) the %h specifier expands to `.'.  For files which
+are themselves directories and contain a slash (including
+.BR /,
+), %h expands to the empty string.  See the
+.B EXAMPLES
+section for an example.
 .IP %H
 Starting-point under which file was found.
 .IP %i
@@ -2265,6 +2278,25 @@ find the first one:
 .B find / -name needle -print -quit
 .fi
 
+For some corner-cases, the interpretation of the
+.B %f
+and
+.B %h
+format directives of
+.B \-printf
+is not obvious.  Here is an eample including some output.
+
+.nf
+.B $ find . .. / /tmp /tmp/TRACE compile compile/64/tests/find -maxdepth 0 -printf '[%h][%f]\en'
+.B [.][.]
+.B [.][..]
+.B [][/]
+.B [][tmp]
+.B [/tmp][TRACE]
+.B [.][compile]
+.B [compile/64/tests][find]
+.fi
+
 .SH EXIT STATUS
 .PP
 .B find
-- 
2.20.1

