Hi Marc, Marc Espie wrote on Mon, Oct 09, 2023 at 07:19:51AM +0200: > On Mon, Oct 09, 2023 at 01:58:27PM +1100, Jonathan Gray wrote: >> somebody wrote:
>>> So tldr: `man backtrace` should name the required linker flag (-lexecinfo) >> from mdoc(7): >> >> .\" .Sh LIBRARY >> .\" For sections 2, 3, and 9 only. >> .\" Not used in OpenBSD. >> >> note about it not being used added by jmc@ in 2010 >> >> Only use in base is in libelf. > Independently of using LIBRARY or not, functions not in libc > should probably mention the library somewhere in the manpage ? Let's look at the dimensions of the problem first: library number of manual page files ------- --------------------------- libcrypto 440 libssl 125 libtls 12 libcurses 64 libform 23 libmenu 23 libpthread 70 libm 63 libelf 48 libfido2 28 libutil 26 libfuse 15 libevent 10 /* work in progress */ libkvm 9 libarch 8 libagentx 1 libcbor 0 /* oops */ libedit 1 libexpat 0 /* oops */ libkeynote 1 libl 0 /* oops */ libossaudio 1 libpanel 1 libpcap 1 libradius 1 librpcsvc 0 /* oops */ libskey 1 libsndio 3 libusbhid 1 liby 0 /* oops */ libz 1 So there are: * giant libraries like crypto+ssl * large libraries like curses+form+menu, pthread, m, elf * medium size libraries like fido2, util, fuse, tls, event * and many single-page libraries For the single-page libraries, adding a single line like .Sh SYNOPSIS .No /* Ev LDFLAGS Ns = Ns Fl lagentx No */ .Pp .In agentx.h would certainly be acceptable because those are typically large pages such that one more line is not a significant waste, nor is it repetitive. Perhaps the same is even acceptable for medium size libraries. I not sure it's a good idea for beasts like crypto, curses, or libm. That would touch large numbers of pages, i.e. incur a higher cost, for a smaller benefit, given that most people using libcrypto likely already know they need -lcrypto, as deraadt@ explained. Maybe we could also mention the needed LDFLAGS in the crypto(3), ssl(3), and curses(3) pages - but no such approach is available for libraries like libm that neither have nor need such a central starting page. The way most other systems are doing this is horrible. The .Lb macro is among the worst-designed macros of the mdoc(7) language, to such a massive degree that we have essentially deprecated it in OpenBSD and removed support for most of its functionality from mandoc(1). There are two problems with its design. The first is that it is designed to maintain a catalog of library description strings, but such a catalog is completely unmaintainable. Each time a single operating system wants to change or add a library description string, both groff(1) and mandoc(1) have to be changed *in each and every operating system*. Groff totally fails to do that. For a time, kristaps@ and myself tried to more or less keep up with the task in mandoc(1), but it never really worked, so i have mostly removed .Lb support from mandoc(1) some time ago. Different operating systems tend to patch it back into mandoc(1) to varying degrees and use operating system specific library description strings, which creates the second problem: manual pages using .Lb are not portable. The groff(1) and mandoc(1) commands on one system cannot format manual pages from another system as intended. It isn't even unusual that library names clash among systems, which results in wrong or misleading library description strings being printed. On top of that, the LIBRARY section is among the worst-designed sections in manual pages. A manual page ought to start with the most important information. This section is near the very top but clearly not more important than the SYNOPSIS. Introducing a new section that almost never contains more than a single line is obviously a terrible idea. And finally, *if* we want to provide this information, it clearly belongs into the SYNOPSIS because the SYNOPSIS is the place where a summary of syntactic information ought to be provided. For systems like FreeBSD, the problem is far more dire than for us because FreeBSD actively encourages an unchecked proliferation of libraries, including large numbers of libraries that serve obscure and niche purposes. But that only means that they suffer from the problems explained above much more than we do, not that the LIBRARY/.Lb "solution" they are stuck with is any better for them than it would be for us. Consequently, using LIBRARY/.Lb in OpenBSD is out of the question. Do you think we should get started by mentioning the needed LDFLAGS for the single-page libraries in a way similar to what i suggested above? For those, it's probably most useful and least intrusive. Yours, Ingo
