bin/59625: [PATCH] usr.bin/man: support -l option

[schwarze%openbsd.org@localhost]

>Number:         59625
>Category:       bin
>Synopsis:       [PATCH] usr.bin/man: support -l option
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    bin-bug-people
>State:          open
>Class:          change-request
>Submitter-Id:   net
>Arrival-Date:   Tue Sep 02 14:15:00 +0000 2025
>Originator:     Ingo Schwarze
>Release:        -current  Sep 2 14:13:07 UTC 2025
>Organization:
OpenBSD and mandoc
>Environment:
N/A, missing feature found by reading the documentation and reading the source code, not by running it
>Description:
While it is generally not advisable to format manual pages at software build time and manual pages should instead normally be installed unformatted, in man(7) or mdoc(7) source form, some software packages, for a variety of reasons, do have a need to format a manual page at build time, which raises the question which command packages should use for that purpose if they want their build system to be as portable as possible.  The traditional way to format a manual page, of course, is by running the nroff(1) command, but some operating systems (for example, OpenBSD and some Linux distros using mandoc by default) no longer install groff(1) by default.  While running mandoc(1) would work on NetBSD and most other *BSDs, many Linux distros and most commercial Unixes do not install mandoc by default.  Some software packages run commands like "man ./manpage.1" (notice the ./ in that command), a quirky syntax that was never supported by traditional Unix nor by any version of the CSRG's BSD.  B
 ecause that syntax has been supported by man-1.5 (formerly often used in Linux) since at least 1998 and by man-db (nowadays normally used on Linux) since at least 2001, it is fairly portable (and also supported by NetBSD and FreeBSD, but no longer by OpenBSD).  This syntax has many problems: it is ambiguous (some manual page names do contain slashes, for example about two dozen in NetBSD), it is very confusing because  "man ./manpage.1" and "man manpage.1" have different meaning, which is highly counter-intuitive, it is arguably too magical and unclear because it relies too much on guessing what the user may mean rather than doing what the user says, and it is hard to document.  For details, see the recent discussion on the man-db mailing list starting at https://lists.nongnu.org/archive/html/man-db-devel/2025-08/msg00000.html .

In any case, the result of that discussion was that the maintainers of all widely-used man(1) implementations and all widely-used manual page formatters agreed that "man ./manpage.1" is an ill-designed syntax - specifically, Colin Watson (man-db), G. Branden Robinson (groff), and myself (mandoc).  So using that syntax should not be recommended to people writing portable build systems.

All three of us also agree that the syntax "man -l manpage.1" that has been supported by man-db for about two decades and by the mandoc implementation of man(1) for about one decade is better designed, unambigous, and is easy and straightforward to document, so we would like to start recommending that syntax for portable build systems.

Consequently, i think that it would be valuable if the man(1) implementation of NetBSD, which is also the currently maintained version of the original BSD man(1), would support -l.  The attached patch implements and documents it.

If -l support is added, i think support for "man ./manpage.1" should probably be kept for a few years to ensure a smooth transition.  After that, a decision can be made to either delete support for "man ./manpage.1" or to keep it for good - either way, that is out of the scope of this patch.

You are free to use this patch under the license already at the top of the files man.c and man.1.
If you want to credit the author, that is Ingo Schwarze <schwarze%openbsd.org@localhost>, but i do not insist on being credited, this is not a particularly large or difficult patch.
>How-To-Repeat:
 $ cd /usr/src/usr.bin/man
 $ man -l man.1
man: unknown option -- l
>Fix:
Hmm, there is no way to submit the patch via this web form, so i'll submit the patch separately after opening this ticket.