[PATCH] doc: note the relationship between realpath and readlink

[Pádraig Brady]

Now that `realpath` is widely available, recommend it
over the less cross compatible `readlink -f`.

* doc/coreutils.texi (realpath invocation): Mention why realpath
is the preferred command for canonicalization.
(readlink invocation): Recommend realpath for canonicalization.
* man/readlink.x: Likewise.
---
 doc/coreutils.texi | 9 ++++++++-
 man/readlink.x     | 2 ++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 629136b..4935b80 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -10260,7 +10260,8 @@ of a symbolic link, it produces no output and exits 
with a nonzero exit code.
 
 @command{readlink} outputs the absolute name of the given files which contain
 no @file{.}, @file{..} components nor any repeated separators
-(@file{/}) or symbolic links.
+(@file{/}) or symbolic links.  Note the @command{realpath} command is the
+preferred command to use for canonicalization.  @xref{realpath invocation}
 
 @end table
 
@@ -13685,6 +13686,12 @@ all but the last component of the specified files must 
exist.  Synopsis:
 realpath [@var{option}]@dots{} @var{file}@dots{}
 @end example
 
+The file name canonicalization functionality overlaps with that of the
+@command{readlink} command, but this is the preferred command for
+canonicalization as it's a more suitable command name, and its syntax
+is more compatible across systems.  In addition this command supports
+relative file name processing functionality.
+
 The program accepts the following options.  Also see @ref{Common options}.
 
 @table @samp
diff --git a/man/readlink.x b/man/readlink.x
index 6b28bca..3141cd2 100644
--- a/man/readlink.x
+++ b/man/readlink.x
@@ -2,5 +2,7 @@
 readlink \- print resolved symbolic links or canonical file names
 [DESCRIPTION]
 .\" Add any additional description here
+Note realpath(1) is the preferred command to use
+for canonicalization functionality.
 [SEE ALSO]
 readlink(2), realpath(1), realpath(3)
-- 
2.5.5