diff --git a/contrib/mandoc/mdoc.7 b/contrib/mandoc/mdoc.7
index 90f5600c59a..7346cf25da6 100644
--- a/contrib/mandoc/mdoc.7
+++ b/contrib/mandoc/mdoc.7
@@ -196,8 +196,14 @@ and
 .Ic \&Nd .
 .It Em LIBRARY
 The name of the library containing the documented functions.
-Using this section is no longer recommended.
-If any
+The syntax for this is as follows:
+.Bd -literal -offset indent
+\&.Lb libm
+.Ed
+.Pp
+Using this section is no longer recommended outside
+.Fx .
+If writing for other operating systems, and any
 .Ic \&Lb
 macro is needed, put it at the beginning of the
 .Em SYNOPSIS
@@ -223,7 +229,7 @@ Commands should be ordered alphabetically.
 .Pp
 For the second, function calls (sections 2, 3, 9):
 .Bd -literal -offset indent
-\&.Lb libname \e" unless the functions are in libc
+\&.Lb libname \e" unless on FreeBSD or the functions are in libc
 \&.In header.h
 \&.Vt extern const char *global;
 \&.Ft char *
@@ -1880,7 +1886,30 @@ See also
 .Tg Lb
 .It Ic \&Lb Cm lib Ns Ar name Op Cm lib Ns Ar name ...
 Specify one or more libraries to link against.
-Putting this macro at the beginning of the
+.Pp
+If used in the
+.Em LIBRARY
+section, the
+.Ar name
+parameter may be a system library, such as
+.Cm z
+or
+.Cm pam ,
+in which case a small library description is printed next to the linker
+invocation; or a custom library, in which case the library name is
+printed in quotes.
+This is most commonly used in the
+.Em LIBRARY
+or
+.Em SYNOPSIS
+sections, as described in
+.Sx MANUAL STRUCTURE.
+.Pp
+Examples:
+.Dl \&.Lb libz
+.Dl \&.Lb libmandoc
+.Pp
+In other operating systems, putting this macro at the beginning of the
 .Em SYNOPSIS
 section is recommended, in which case it prints this comment:
 .D1 /* Fl l Ns Ar name Oo Fl l Ns Ar name ... Oc */