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...

[LDVG]

Hi,

Apologies for the slow response.

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.

Indeed, we should certainly fix this. Thank you for pointing it out!

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

Unfortunately, we rely on the downstream distribution(s) of mandoc; there's nothing for us to patch since we're not building it.

We also try to accommodate other implementations, such as man-db, which appears a little more confused by this (note the missing line break):

$ man -l man/eddsa_pk_new.3
...
SYNOPSIS
       library “libfido2” libcbor libcrypto libz #include <openssl/evp.h>
       #include <fido/eddsa.h>
...

While I appreciate the improved .Lb macro, it's unclear to me how we would proceed without "breaking" other distributions and we'd likely have to wait until support for this format is picked up before changing our sources.

In the meantime, I would probably suggest committing this patch to the OpenBSD tree instead.

[ischwarze]

Hello Ludvig,

Apologies for the slow response.

No sweat, this is not a time-critical matter.

Unfortunately, we rely on the downstream distribution(s) of mandoc;
there's nothing for us to patch since we're not building it.

I see.

We also try to accommodate other implementations, such as man-db,

It may seem like nitpicking, but just so you fully understand what is really going on.

The man-db program is purely a manual page search and display program with no parsing or formatting capabilities of its own, so it has nothing to do with this. Many other man(1) implementations exist that only implement displaying, but no formatting, for example PWB/UNIX man (1977), Version 7 AT&T UNIX man (1979), 4.0BSD man (1980), AT&T System III UNIX man (1982), AT&T System V UNIX man (1983), 4.3BSD man (1986), Eaton man (1993), man-1.6 (2005-2010, some Linuxes may still use it, at least optionally), FreeBSD man (actively maintained, also used in macOS), Solaris man (actively maintained by Oracle in Solaris 11), and probably some others.

The program you are waiting for to more nicely format the new syntax is the formatter. By far the most widespread formatter is GNU roff, https://www.gnu.org/software/groff/ . I'm also a committer there and
am planning to implement full support (including nits like pretty line breaking) there shortly, specifically, in https://manpages.debian.org/unstable/groff/groff_mdoc.7.en.html . When that is done, you may have to wait until groff makes the upcoming groff-1.24 release, then Debian integrates that into unstable, then into testing, then into a release, and then Ubuntu picks it up. That may take a few years but i estimate you might get full support around 2028-2030. The industry moves at a glacial pace... :-)

A few other roff implementations exist, for example Heirloom Doctools troff, Plan 9 troff from User Space, Neatroff - but these are extremely rarely used as manual page formatters, and some don't even support the mdoc(7) language you are using at all. So i think you don't need to worry about niche roff implementations. When you target groff and mandoc, you should be good for 99% of users.

With mandoc, things are simpler because mandoc(1) includes all the above functionality: parsing, formatting, searching and display. So in a nutstall, mandoc = man-db + groff (for the purposes of manual pages only, not for the purposes of general-purpose typesetting, of course, where groff provides much more functionality than mandoc).

While I appreciate the improved .Lb macro, it's unclear to me how we would proceed
without "breaking" other distributions and we'd likely have to wait until support for this format
is picked up before changing our sources.

If you aim for perfect formatting (as opposed to the intelligible, but slightly ugly formatting that groff gives you right now), then waiting for perfect support in groff is a reasonable option.

In the meantime, I would probably suggest committing this patch to the OpenBSD tree instead.

Done:
https://marc.info/?l=openbsd-cvs&m=175201927205030
https://cvsweb.openbsd.org/src/lib/libfido2/man/fido_init.3

If you have additional questions, feel free to ask!

[LDVG]

It may seem like nitpicking, but just so you fully understand what is really going on.

Actually, I really appreciate it!

The program you are waiting for to more nicely format the new syntax is the formatter. By far the most widespread formatter is GNU roff, https://www.gnu.org/software/groff/ .

Yes, you're quite correct.

I'm also a committer there and am planning to implement full support (including nits like pretty line breaking) there shortly [...]

Excellent!

That may take a few years but i estimate you might get full support around 2028-2030. The industry moves at a glacial pace... :-)

Ah yes, such is the way of things sometimes 🙂

Thank you for your contribution (here and elsewhere!)

[LDVG]

(converting this to a future TODO)