doc: clarify current realpath --relative-base behavior

For compatibility with MacOS relpath(1), as seen here:

http://opensource.apple.com/source/bootstrap_cmds/\
bootstrap_cmds-79/relpath.tproj/relpath.c

we implemented 'realpath --relative-base=dir1 --relative-to=dir2 file'
in the same way as 'relpath -d dir1 dir2 file'.  This can result
in --relative-base rendering --relative-to as a no-op if dir1 is a
child of dir2.  Document this.

* doc/coreutils.texi (realpath invocation): Mention restriction.

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 835c245..10be715 100644 (file)
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -12905,7 +12905,9 @@ This option is valid when used with @option{--relative-to}, and will restrict
 the output of @option{--relative-to} so that relative names are output,
 only when @var{file}s are descendants of @var{base}.  Otherwise output the
 absolute file name.  If @option{--relative-to} was not specified, then
-the descendants of @var{base} are printed relative to @var{base}.
+the descendants of @var{base} are printed relative to @var{base}.  If
+@option{--relative-to} is specified, then that directory must be a
+descendant of @var{base} for this option to have an effect.
 Note: this option honors the @option{-m} and @option{-e}
 options pertaining to file existence.  For example: