man/*.3: use .Lb in the SYNOPSIS section

[ischwarze]

Hello,

the https://mandoc.bsd.lv/ and https://www.openbsd.org/ projects have recently introduced a new way to use the mdoc(7) .Lb macro: as the first macro in the SYNOPSIS section. With bleeding-edge mandoc(1), this results in output looking like this:

$ man -l man/fido_init.3
[...]
SYNOPSIS
/* -lfido2 -lcbor -lcrypto -lz */
#include <fido.h>
[...]

The advantages compared to the old way of using the .Lb macro (which was introduced around the year 2000 in FreeBSD, NetBSD and GNU roff) are:

• Very concise output informing the user about the required linker options.
• The C comment syntax agrees with how the rest of the SYNOPSIS is presented.
• No need for an excessively verbose LIBRARY section distracting the reader.
• No need for maintaining lists of library descriptions inside the mandoc and roff formatters that are very hard to maintain, usually out of date, often inconsistent among formatters and operating systems, and sometimes even confict with each other.

All other mdoc(7) library manual pages in OpenBSD have already been adjusted, see for example https://man.openbsd.org/SSL_CTX_new.3 . libfido2 is the last base system library to handle. Damien Miller <djm@>
suggested to first send the patch uspream before committing to OpenBSD.

The new style of using .Lb has been presented on both the mandoc and groff mailing lists, and nobody voiced concerns. An illumos developer spoke up and supported the general direction, which is not too surprising because illumos has already put .Lb macros into the SYNOPSIS sections of a small number of manual pages some years ago, so establishing the new style will improve formatting for them.

I will later write and commit a patch to groff_mdoc(7) supporting this new style, so long-term compatibility issues are not expected.

Regarding short-term compatibilty (until operating systems update their formatters), the output is not too pretty, but not unitelligible either. For example, with old mandoc, the output looks as follows:

$ /oldbin/mandoc man/fido_init.3 | less
[...]
SYNOPSIS
library “libfido2” libcbor libcrypto libz
#include <fido.h>

With old groff, output looks similar, but of course only until operating systems update.

I think updating library documentation early provides more benefit for users than waiting - those users already having up-to-date formatters get ideal output at once, all others get more information, even if - for the first time - in a slightly ugly form.

[ischwarze]

It appears your CI is running an outdated version of mandoc,
this is from one of the clang builds on ubuntu:

cd /home/runner/work/libfido2/libfido2/build-Debug/man && mandoc -T lint -W warning eddsa_pk_new.3 > eddsa_pk_new.3.lint
make[2]: *** [man/CMakeFiles/man_lint.dir/build.make:107: man/eddsa_pk_new.3.lint] Error 2
make[2]: *** Deleting file 'man/eddsa_pk_new.3.lint'

The meaning of "Error 2" is "warning", see https://man.openbsd.org/mandoc.1#EXIT_STATUS .
When you do such strict validation that a mandoc warning kills the build, it would probably make sense to not redirect the actual warning message to a file that you immediately delete, but just let the mandoc -T lint output appear in the build log such that users see what the problem is.
Anyway, even without the message, i'm able to reproduce with an old mandoc:

$ /co/mandoc-1.14.6/mandoc -T lint -W warning eddsa_pk_new.3
mandoc: eddsa_pk_new.3:39:5: WARNING: unknown library name: Lb libfido2

You can likely resolve that by applying this (committed) patch to your mandoc:

https://marc.info/?l=mandoc-source&m=174912683805793

I have no idea what "You're not authorized to push to this branch" means: of course i'm not authorized to push to others' repositories, that's why i'm opening a pull request, duh. I'm absolutely not willing to waste my time on creating branches or reading interminable, usually unintelligible Github "documentation". I have accumulated more than 6000 commits in free software projects over the years but Github is nothing but a totally unusable mess. I hope you can figure out how to get the patch into your repository. Sorry for the rant...