mandoc: Document that .Lb can now take multiple arguments.

mandoc: Document that .Lb can now take multiple arguments.

[schwarze]

Log Message:
-----------
Document that .Lb can now take multiple arguments.
Document the new usage pattern for .Lb.
Deprecate the LIBRARY section.

Modified Files:
--------------
    mandoc:
        mdoc.7

Revision Data
-------------
Index: mdoc.7
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc.7,v
diff -Lmdoc.7 -Lmdoc.7 -u -p -r1.297 -r1.298
--- mdoc.7
+++ mdoc.7
@@ -1,7 +1,7 @@
 .\" $Id$
 .\"
+.\" 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
@@ -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 alphabeticall
 .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 semico
 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 numb
 .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
--
 To unsubscribe send an email to source+unsubscribe@mandoc.bsd.lv