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.
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: