doc: note the relationship between realpath and readlink

* doc/coreutils.texi (realpath invocation): Mention that realpath
is the preferred command for canonicalization.
(readlink invocation): Likewise.
* man/readlink.x: Likewise.

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 629136b0102053adf549ccb6abe65c69fb98576c..3eac96b7dff29a40b25bbf01e344349d68752c07 100644 (file)
--- 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,11 @@ 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.  This is the preferred command for
+canonicalization as it's a more suitable and standard name.  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 6b28bca4732105d5d2c860904953a8bdc51ad9f6..3141cd2537274f74729b6ffb1dc6edfd8b3a18ea 100644 (file)
--- 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)