git: 4f3662233a0c - stable/14 - mdoc.7: Revert upstream changes to Lb/LIBRARY

The branch stable/14 has been updated by ziaee:

URL: https://cgit.FreeBSD.org/src/commit/?id=4f3662233a0c7a4ed328a008b913e87ec0421295

commit 4f3662233a0c7a4ed328a008b913e87ec0421295
Author:     Alexander Ziaee <[email protected]>
AuthorDate: 2026-05-22 18:09:23 +0000
Commit:     Alexander Ziaee <[email protected]>
CommitDate: 2026-08-06 22:28:49 +0000

    mdoc.7: Revert upstream changes to Lb/LIBRARY
    
    Since this manual describes the mdoc syntax throughout the ecosystem,
    I had to blend what we had before with what upstream is doing now.
    
    Thanks:         adrian
    MFC after:      3 days (we shipped this doc in 15.0/14.4)
    Reviewed by:    ivy, mhorne, des, adrian
    Discussed with: arch@
    Differential Revision:  https://reviews.freebsd.org/D56153
    
    (cherry picked from commit 4e2bf6e90a65bee317e4dd379e098ba2eb5d8c0d)
---
 contrib/mandoc/mdoc.7 | 37 +++++++++++++++++++++++++++++++++----
 1 file changed, 33 insertions(+), 4 deletions(-)

diff --git a/contrib/mandoc/mdoc.7 b/contrib/mandoc/mdoc.7
index 6c2d3568baa6..03bceadbeba5 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 */