Rewrite symlink handling.

Reviewed by:	bapt

1 files changed, 14 insertions, 39 deletions

diff --git a/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
index 3ba20446fe..2bf0d93d89 100644
--- a/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
@@ -81,56 +81,31 @@
     <sect2 xml:id="staging-symlink">
       <title>Handling Symbolic Links</title>
 
-      <para>When creating a symlink, there are two cases, either the
-	source and target are both within
-	<filename>${PREFIX}</filename>.  In that case, use
-	<command>${RLN}</command>.  In the other case, if one or both
-	of the paths are outside of <filename>${PREFIX}</filename>
-	use <command>${LN} -s</command> and only prepend
-	<filename>${STAGEDIR}</filename> to the target's path.</para>
+      <para>When creating a symbolic link, relative ones are strongly
+	recommended.  Use <command>${RLN}</command> to create relative
+	symbolic links.  It uses &man.install.1; under the hood to
+	automatically figure out the relative link to create.</para>
 
       <example xml:id="staging-ex1">
-	<title>Inside <filename>${PREFIX}</filename>, Create Relative
-	  Symbolic Links</title>
+	<title>Create Relative Symbolic Links Automatically</title>
 
 	<para><command>${RLN}</command> uses &man.install.1;'s
 	  relative symbolic feature which frees the porter of
 	  computing the relative path.</para>
 
-	<programlisting>${RLN} ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so.42</replaceable> ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so</replaceable></programlisting>
+	<programlisting>${RLN} ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so.42</replaceable> ${STAGEDIR}${PREFIX}/lib/<replaceable>libfoo.so</replaceable>
+${RLN} ${STAGEDIR}${PREFIX}/libexec/foo/<replaceable>bar</replaceable> ${STAGEDIR}${PREFIX}/bin/<replaceable>bar</replaceable>
+${RLN} ${STAGEDIR}<replaceable>/var/cache/foo</replaceable> ${STAGEDIR}${PREFIX}/share/<replaceable>foo</replaceable></programlisting>
 
 	<para>Will generate:</para>
 
 	<screen>&prompt.user; <userinput>ls -lF ${STAGEDIR}${PREFIX}/lib</userinput>
-  lrwxr-xr-x  1 nobody  nobody    181 Aug  3 11:27 libfoo.so@ -> libfoo.so.42
-  -rwxr-xr-x  1 nobody  nobody     15 Aug  3 11:24 libfoo.so.42*</screen>
-
-	<para>When used with paths not in the same directory:</para>
-
-	<programlisting>${RLN} ${STAGEDIR}${PREFIX}/libexec/foo/<replaceable>bar</replaceable> ${STAGEDIR}${PREFIX}/bin/<replaceable>bar</replaceable></programlisting>
-
-	<para>Will automatically generate the relative symbolic
-	  links:</para>
-
-	<screen>&prompt.user; <userinput>ls -lF ${STAGEDIR}${PREFIX}/bin</userinput>
-  lrwxr-xr-x  1 nobody  nobody    181 Aug  3 11:27 bar@ -> ../libexec/foo/bar</screen>
-      </example>
-
-      <example xml:id="staging-ex2">
-	<title>Outside <filename>${PREFIX}</filename>, Create Absolute
-	  Symbolic Links</title>
-
-	<para>When creating a symbolic link outside of
-	  <filename>${PREFIX}</filename>, the source must not contain
-	  <filename>${STAGEDIR}</filename>, the target, however,
-	  must:</para>
-
-	<programlisting>${LN} -sf <replaceable>/var/cache/${PORTNAME}</replaceable> ${STAGEDIR}${PREFIX}/share/<replaceable>${PORTNAME}</replaceable></programlisting>
-
-	<para>Will generate:</para>
-
-	<screen>&prompt.user; <userinput>ls -lF ${STAGEDIRDIR}${PREFIX}/share</userinput>
-  lrwxr-xr-x  1 nobody  nobody    181 Aug  3 11:27 foo@ -> /var/cache/foo</screen>
+lrwxr-xr-x  1 nobody  nobody    181 Aug  3 11:27 libfoo.so@ -> libfoo.so.42
+-rwxr-xr-x  1 nobody  nobody     15 Aug  3 11:24 libfoo.so.42*
+&prompt.user; <userinput>ls -lF ${STAGEDIR}${PREFIX}/bin</userinput>
+lrwxr-xr-x  1 nobody  nobody    181 Aug  3 11:27 bar@ -> ../libexec/foo/bar
+&prompt.user; <userinput>ls -lF ${STAGEDIRDIR}${PREFIX}/share</userinput>
+lrwxr-xr-x  1 nobody  nobody    181 Aug  3 11:27 foo@ -> ../../../var/cache/foo</screen>
       </example>
     </sect2>
   </sect1>