From 34023817cb0225b50779a546a58e057e5e920d2c Mon Sep 17 00:00:00 2001
From: Pádraig Brady <P@draigBrady.com>
Date: Wed, 3 Apr 2013 18:33:43 +0100
Subject: doc: add details on ln --relative symlink resolution

* doc/coreutils.texi (ln invocation): Describe how symlinks are
resolved with --relative, and give an example showing the greater
control available through realpath(1).
* tests/ln/relative.sh: Add a test to demonstrate full symlink
resolution, in a case where it might not be wanted.
---
 doc/coreutils.texi | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index dfa9b1c21..4cfe4c50c 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -9798,8 +9798,24 @@ ln -srv /a/file /tmp
 '/tmp/file' -> '../a/file'
 @end smallexample
 
+Relative symbolic links are generated based on their canonicalized
+containing directory, and canonicalized targets.  I.E. all symbolic
+links in these file names will be resolved.
 @xref{realpath invocation}, which gives greater control
-over relative file name generation.
+over relative file name generation, as demonstrated in the following example:
+
+@example
+@verbatim
+ln--relative() {
+  test "$1" = --no-symlinks && { nosym=$1; shift; }
+  target="$1";
+  test -d "$2" && link="$2/." || link="$2"
+  rtarget="$(realpath $nosym -m "$target" \
+              --relative-to "$(dirname "$link")")"
+  ln -s -v "$rtarget" "$link"
+}
+@end verbatim
+@end example
 
 @item -s
 @itemx --symbolic
-- 
cgit v1.2.3-54-g00ecf