===================================================================
RCS file: /cvs/mandoc/mdoc.7,v
retrieving revision 1.297
retrieving revision 1.298
diff -u -p -r1.297 -r1.298
--- mandoc/mdoc.7	2025/05/21 17:10:48	1.297
+++ mandoc/mdoc.7	2025/06/05 13:48:19	1.298
@@ -1,7 +1,7 @@
-.\" $Id: mdoc.7,v 1.297 2025/05/21 17:10:48 schwarze Exp $
+.\" $Id: mdoc.7,v 1.298 2025/06/05 13:48:19 schwarze Exp $
 .\"
+.\" Copyright (c) 2010-2021, 2024, 2025 Ingo Schwarze <schwarze@openbsd.org>
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2010, 2011, 2013-2020 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: May 21 2025 $
+.Dd $Mdocdate: June 5 2025 $
 .Dt MDOC 7
 .Os
 .Sh NAME
@@ -192,15 +192,13 @@ See
 and
 .Ic \&Nd .
 .It Em LIBRARY
-The name of the library containing the documented material, which is
-assumed to be a function in a section 2, 3, or 9 manual.
-The syntax for this is as follows:
-.Bd -literal -offset indent
-\&.Lb libarm
-.Ed
-.Pp
-See
-.Ic \&Lb .
+The name of the library containing the documented functions.
+Using this section is no longer recommended.
+If any
+.Ic \&Lb
+macro is needed, put it at the beginning of the
+.Em SYNOPSIS
+section instead.
 .It Em SYNOPSIS
 Documents the utility invocation syntax, function call syntax, or device
 configuration.
@@ -222,6 +220,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
 \&.In header.h
 \&.Vt extern const char *global;
 \&.Ft "char *"
@@ -492,7 +491,7 @@ in the alphabetical
 .El
 .Ss Semantic markup for function libraries
 .Bl -column "Brq, Bro, Brc" description
-.It Ic \&Lb Ta function library (one argument)
+.It Ic \&Lb Ta function library (>0 arguments)
 .It Ic \&In Ta include file (one argument)
 .It Ic \&Fd Ta other preprocessor directive (>0 arguments)
 .It Ic \&Ft Ta function type (>0 arguments)
@@ -1861,26 +1860,29 @@ but not the whitespace before the semicolon.
 See also
 .Ic \&Bl .
 .Tg Lb
-.It Ic \&Lb Cm lib Ns Ar name
-Specify a library.
-.Pp
-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
+.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
 .Em SYNOPSIS
-section as described in
-.Sx MANUAL STRUCTURE .
+section is recommended, in which case it prints this comment:
+.D1 /* Fl l Ns Ar name Oo Fl l Ns Ar name ... Oc */
 .Pp
-Examples:
-.Dl \&.Lb libz
-.Dl \&.Lb libmandoc
+If used outside the
+.Em SYNOPSIS ,
+this macro prints
+.D1 library Dq Cm lib Ns Ar name
+instead.
+For system libraries, some operating systems
+print a short library description.
+.Pp
+Example:
+.Bd -literal -offset indent -compact
+\&.Sh SYNOPSIS
+\&.Lb libtls libssl libcrypto
+\&.In tls.h
+\&.Ft int
+\&.Fn tls_init void
+.Ed
 .Tg Li
 .It Ic \&Li Ar word ...
 Unquoted in-line literal display, always set in a constant-width font.
@@ -3035,7 +3037,7 @@ then the macro accepts an arbitrary number of argument
 .It Ic \&Hf  Ta    \&No     Ta    \&No     Ta    n
 .It Ic \&Ic  Ta    Yes      Ta    Yes      Ta    >0
 .It Ic \&In  Ta    Yes      Ta    Yes      Ta    1
-.It Ic \&Lb  Ta    \&No     Ta    \&No     Ta    1
+.It Ic \&Lb  Ta    \&No     Ta    \&No     Ta    >0
 .It Ic \&Li  Ta    Yes      Ta    Yes      Ta    >0
 .It Ic \&Lk  Ta    Yes      Ta    Yes      Ta    >0
 .It Ic \&Lp  Ta    \&No     Ta    \&No     Ta    0