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: [email protected]
Reporter: [email protected]
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 <[email protected]>,
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.
