svn commit: r54516 - head/en_US.ISO8859-1/books/porters-handbook/special

[Mathieu Arnold]

Author: mat
Date: Wed Sep 23 15:13:21 2020
New Revision: 54516
URL: https://svnweb.freebsd.org/changeset/doc/54516

Log:
  Rewrite symlink handling.
  
  Reviewed by:	bapt

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml	Wed Sep 23 06:48:38 2020	(r54515)
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml	Wed Sep 23 15:13:21 2020	(r54516)
@@ -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>