Index: share/mk/bsd.README
===================================================================
--- share/mk/bsd.README
+++ share/mk/bsd.README
@@ -313,16 +313,13 @@
 		and is only valid inside of the /usr/src tree.
 		Rather than use LDADD=-lname use LIBADD=name.
 
-LINKS		The list of binary links; should be full pathnames, the
-		linked-to file coming first, followed by the linked
-		file.  The files are hard-linked.  For example, to link
-		/bin/test and /bin/[, use:
-
-			LINKS=	/bin/test /bin/[
+LINKS		List of hard links. See bsd.links.mk for more details.
 
 MAN		Manual pages.  If no MAN variable is defined,
 		"MAN=${PROG}.1" is assumed. See bsd.man.mk for more details.
 
+MLINKS		List of manual page links. See bsd.man.mk for more details.
+
 PROG		The name of the program to build.  If not supplied, nothing
 		is built.
 
@@ -385,8 +382,10 @@
 		Each of the targets will execute the same target in the
 		subdirectories.
 
+SYMLINKS	List of symbolic links. See bsd.links.mk for more details.
+
 The include file <bsd.prog.mk> includes the file named "../Makefile.inc"
-if it exists, as well as the include file <bsd.man.mk>.
+if it exists, as well as the include file <bsd.links.mk> and <bsd.man.mk>.
 
 Some simple examples:
 
@@ -530,11 +529,15 @@
 		will be built.  NO_PIC can be set to only build a static
 		library.
 
+LINKS		List of hard links. See bsd.links.mk for more details.
+
 LINTLIBDIR	Target directory for lint libraries.
 
 MAN		The manual pages to be installed. See bsd.man.mk for more
 		details.
 
+MLINKS		List of manual page links. See bsd.man.mk for more details.
+
 SHLIB		Like LIB but only builds a shared library.
 
 SHLIB_CXX	Like LIB_CXX but only builds a shared library.
@@ -549,7 +552,7 @@
 		versions of make.)
 
 The include file <bsd.lib.mk> includes the file named "../Makefile.inc"
-if it exists, as well as the include file <bsd.man.mk>.
+if it exists, as well as the include file <bsd.links.mk> and <bsd.man.mk>.
 
 It has rules for building profiled objects; profiled libraries are
 built by default.
@@ -557,6 +560,35 @@
 Libraries are ranlib'd before installation.
 
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+The include file <bsd.links.mk> is included by bsd.*.mk snippets that have
+included bsd.init.mk. At the time of writing, this includes bsd.lib.mk and
+bsd.prog.mk. bsd.links.mk contains business logic for creating hardlinks
+and symlinks for install targets.
+
+bsd.links.mk does not have any user-exposed targets, but instead builds on
+the `realinstall` target provided by bsd.subdir.mk and bsd.sys.mk. It should
+be invoked via the `install` target.
+
+LINKS		The list of binary links; should be full pathnames, the
+		linked-to file coming first, followed by the linked
+		file.  The files are hard-linked.  For example, to link
+		/bin/test and /bin/[, use:
+
+			LINKS=	/bin/test /bin/[
+
+SYMLINKS	The list of symlinks; should be full pathnames, the
+		symlinked-to file coming first, followed by the symlinked
+		file.  The files are symbolic-linked.  For example, to
+		symlink /bin/[ to ./test using relative paths, use:
+
+			SYMLINKS=	test /bin/[
+
+		Alternatively, to symlink /bin/{ to /bin/test using absolute
+		paths, use:
+
+			SYMLINKS=	/bin/test /bin/[
+
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 
 The include file <bsd.test.mk> handles building one or more test programs
 intended to be used in the FreeBSD Test Suite under /usr/tests/.