realpath: improve doc and NEWS

diff --git a/NEWS b/NEWS
index cc4a91303967f732b5e20128d81c79ab6b219e12..d0bd06d4ade5c6463c32abd72cc8f3cc8b9fc309 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -70,27 +70,11 @@ GNU coreutils NEWS                                    -*- outline -*-
   pretended that standard input was not a tty.
   [This bug was present in "the beginning".]
 
-** Changes in behavior
-
-  readlink now defaults to being verbose if the POSIXLY_CORRECT
-  environment variable is set.
-
 ** New Features
 
   basenc supports the --base58 option to encode and decode
   the visually unambiguous Base58 encoding.
 
-  realpath supports the -E option as required by POSIX.  The behavior is
-  the same as realpath with no options.  The corresponding long option
-  is --canonicalize.
-
-  tsort now accepts and ignores -w, to conform to POSIX.1-2024.
-
-** Improvements
-
-  'factor' is now much faster at identifying large prime numbers,
-  and significantly faster on composite numbers greater than 2^128.
-
   stty supports setting arbitrary baud rates on supported systems,
   like Hurd, Linux with glibc >= 2.42, and some BSDs.
   Also on other systems the full set of supported baud rates
@@ -100,6 +84,21 @@ GNU coreutils NEWS                                    -*- outline -*-
   Iranian locale (fa_IR) and for the Ethiopian locale (am_ET), and also
   does so more consistently for the Thailand locale (th_TH.UTF-8).
 
+** Changes to conform better to POSIX.1-2024
+
+  readlink now defaults to being verbose if the POSIXLY_CORRECT
+  environment variable is set.
+
+  realpath now supports -E, which specifies the default behavior.
+  The corresponding long option is --canonicalize.
+
+  tsort now accepts and ignores -w.
+
+** Performance improvements
+
+  'factor' is now much faster at identifying large prime numbers,
+  and significantly faster on composite numbers greater than 2^128.
+
 ** Build-related
 
   cksum was not compilable by Apple LLVM 10.0.0 x86-64, which

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 9038979b4bcfde2c654b766cbe3a1948e6c03c9c..c4dd2f60ddf873586cf945d711c43cddeaa4f63c 100644 (file)
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -15006,13 +15006,20 @@ Exit status:
 @pindex realpath
 @findex realpath
 
-@command{realpath} expands all symbolic links and resolves references to
-@samp{/./}, @samp{/../} and extra @samp{/} characters.  Synopsis:
+The @command{realpath} command outputs a file's canonicalized name,
+which is an absolute file name that contains neither unnecessary
+@samp{/} nor components that are @samp{.}, @samp{..}, or a symbolic link.
+
+Synopsis:
 
 @example
 realpath [@var{option}]@dots{} @var{file}@dots{}
 @end example
 
+By default, @command{realpath} succeeds if every file name component
+but the last names an existing directory.  It ignores trailing slashes
+that are not also leading slashes.
+
 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
@@ -15027,21 +15034,17 @@ The program accepts the following options.  Also see @ref{Common options}.
 @opindex -E
 @opindex --canonicalize
 
-Ensure all but the last component of the specified file name exist.
-Otherwise, @command{realpath} will output a diagnostic unless the
-@option{-q} option is specified, and exit with a nonzero exit code.  A
-trailing slash is ignored.  This option is the default behavior, but is
-included for POSIX compatibility.
+Do not fail merely because the named file does not exist.
+Although this is the default behavior of GNU @code{realpath},
+POSIX does not require this default, so portable applications should
+use an explicit @option{-E}.
 
 @item -e
 @itemx --canonicalize-existing
 @opindex -e
 @opindex --canonicalize-existing
-Ensure that all components of the specified file names exist.
-If any component is missing or unavailable, @command{realpath} will output
-a diagnostic unless the @option{-q} option is specified, and exit with a
-nonzero exit code.  A trailing slash requires that the name resolve to a
-directory.
+Fail if the named file does not exist.
+A trailing slash requires that the name resolve to a directory.
 
 @item -m
 @itemx --canonicalize-missing
@@ -15128,8 +15131,8 @@ By default, @command{realpath} prints the absolute file name of given files
 @example
 @group
 cd /home/user
-realpath /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
-@result{} /usr/bin/sort
+realpath /usr/bin/ ///tmp/.//foo /usr/share/dict/words 1.txt
+@result{} /usr/bin
 @result{} /tmp/foo
 @result{} /usr/share/dict/american-english
 @result{} /home/user/1.txt
@@ -15142,8 +15145,8 @@ the given directory:
 @example
 @group
 realpath --relative-to=/usr/bin \
-         /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
-@result{} sort
+         /usr/bin/ ///tmp/.//foo /usr/share/dict/words 1.txt
+@result{} .
 @result{} ../../tmp/foo
 @result{} ../share/dict/american-english
 @result{} ../../home/user/1.txt
@@ -15157,8 +15160,8 @@ base directory absolute file names are printed:
 @example
 @group
 realpath --relative-base=/usr \
-         /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
-@result{} bin/sort
+         /usr/bin/ ///tmp/.//foo /usr/share/dict/words 1.txt
+@result{} bin
 @result{} /tmp/foo
 @result{} share/dict/american-english
 @result{} /home/user/1.txt
@@ -15173,8 +15176,8 @@ printed as absolute file names:
 @example
 @group
 realpath --relative-to=/usr/bin --relative-base=/usr \
-         /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
-@result{} sort
+         /usr/bin/ ///tmp/.//foo /usr/share/dict/words 1.txt
+@result{} .
 @result{} /tmp/foo
 @result{} ../share/dict/american-english
 @result{} /home/user/1.txt