Index: share/mk/bsd.README
===================================================================
--- share/mk/bsd.README
+++ share/mk/bsd.README
@@ -293,12 +293,7 @@
 		since that's used to link programs as well, so loader
 		specific flags need to be prefixed with -Wl, to work.
 
-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=	${DESTDIR}/bin/test ${DESTDIR}/bin/[
+LINKS		List of hard links. See bsd.links.mk for more details.
 
 MAN		Manual pages (should end in .1 - .9).  If no MAN variable
 		is defined, "MAN=${PROG}.1" is assumed.
@@ -385,8 +380,10 @@
 		SCRIPTSGRP, SCRIPTSMODE, SCRIPTSDIR variables that can be
 		further specialized by SCRIPTS<VAR>_<script>.
 
+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:
 
@@ -524,7 +521,12 @@
 
 LIBMODE		Library mode.
 
-LDADD		Additional loader objects.
+LINKS		List of hard links. See bsd.links.mk for more details.
+
+LDADD		Additional loader objects.  This variable's use is generally
+		combined with DPADD.
+
+		See also: LIBADD.
 
 LIBADD		Additional libraries.  This is for base system libraries
 		and is only valid inside of the /usr/src tree.
@@ -545,10 +547,12 @@
 		Unless used, a simple symlink is created to the real
 		shared object.
 
+SYMLINKS	List of symbolic links. See bsd.links.mk for more details.
+
 LIBRARIES_ONLY	Do not build or install files other than the library.
 
 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.
@@ -556,6 +560,30 @@
 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=	${DESTDIR}/bin/test ${DESTDIR}/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/test and /bin/[, use:
+
+			SYMLINKS=	${DESTDIR}/bin/test ${DESTDIR}/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/.