Date: Mon, 01 Sep 2025 22:04:07 +0000 From: bugzilla-noreply@freebsd.org To: bugs@FreeBSD.org Subject: [Bug 289245] [PATCH] usr.bin/man: support -l option Message-ID: <bug-289245-227@https.bugs.freebsd.org/bugzilla/>
index | next in thread | raw e-mail
https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=289245 Bug ID: 289245 Summary: [PATCH] usr.bin/man: support -l option Product: Base System Version: CURRENT Hardware: Any OS: Any Status: New Severity: Affects Some People Priority: --- Component: bin Assignee: bugs@FreeBSD.org Reporter: schwarze@usta.de Created attachment 263402 --> https://bugs.freebsd.org/bugzilla/attachment.cgi?id=263402&action=edit support -l in usr.bin/man/man.sh 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 FreeBSD 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. Because 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 FreeBSD and NetBSD, but no longer by OpenBSD). This syntax has many problems: it is ambiguous (some manual page names do contain slashes, for example about a dozen in FreeBSD), 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/msg00012.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 FreeBSD, which is not only the most widely used *BSD system, but sees even more users because macOS also relies on it, would support -l. The attached patch implements and documents it. Some remarks regarding the patch and the surrounding code: * It is important that -l is mutually exclusive with -f and -k. Combining it with -w has no value; with man-db, "man -lw" just prints the argument(s); with mandoc, -lw does the same as just -l. In the FreeBSD logic, it's probably best to treat -l and -w as mutually exclusive. I fail to see the reason why -t needs to be mutually exclusive with all these option; nonetheless, for consistency, my patch makes -l and -t mutually exclusive, just like -fkw and -t. * With the growing size of the set of mutually exclusive options, the triangular scheme of detecting and reporting clashes starts to look ugly, but i refrained from mixing any refactoring into this patch. * 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 file man.sh. If you want to credit the author, that is Ingo Schwarze <schwarze@openbsd.org>, but i do not insist on being credited, this is not a particularly large or difficult patch. -- You are receiving this mail because: You are the assignee for the bug.home | help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?bug-289245-227>