Index: share/mk/bsd.README
===================================================================
--- share/mk/bsd.README
+++ share/mk/bsd.README
@@ -285,23 +285,20 @@
 
 			LDADD=-lutil -lcompat
 
-LIBADD		Additional libraries.  This is for base system libraries
-		and is only valid inside of the /usr/src tree.
-		Rather than use LDADD=-lname use LIBADD=name.
-
 LDFLAGS		Additional loader flags. Passed to the loader via CC,
 		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:
+LIBADD		Additional libraries.  This is for base system libraries
+		and is only valid inside of the /usr/src tree.
+		Rather than use LDADD=-lname use LIBADD=name.
 
-			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.
+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 @@
 		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,13 +523,23 @@
 
 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.
 		Rather than use LDADD=-lname use LIBADD=name.
 
-MAN		The manual pages to be installed (use a .1 - .9 suffix).
+LINKS		List of hard links. See bsd.links.mk for more details.
+
+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.
 
 SRCS		List of source files to build the library.  Suffix types
 		.s, .c, and .f are supported.  Note, .s files are preferred
@@ -545,10 +554,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 +567,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/.