On Tue, Aug 26, 2025 at 05:06:03PM +0200, Ingo Schwarze wrote:
this message is about the man-db program https://man-db.nongnu.org/ rather than about roff, but i'm posting it here because manual page questions (including with respect to man-db and other man(1) programs) are often discussed here, whereas the man-db mailing list had no postings since 2023: https://lists.nongnu.org/archive/html/man-db-devel/
That state of affairs won't change if people keep CCing me personally rather than using the list; while I'm fortunately still active and in generally good health, I presume that I'm not immune to entropy and so I prefer to encourage the use of appropriate role addresses. I've CCed the list.
-l, --local-file Activate "local" mode. Format and display local manual files [...] If this option is not used, then man will also fall back to interpreting manual page arguments as local file names if the argument contains a "/" character, since that is a good indication that the argument refers to a path on the file system.
[...]
In OpenBSD, it recently came up that this small feature is not documented for the mandoc implementation of man(1). When i proposed (internally in the project) to document it in a COMPATIBILITY section saying it is supported for man-db compatibility only and discouraging its use, i met opposition and other developers requested that the feature instead be removed, for the following reasons:
In hindsight, I don't love this feature either and I don't think it serves any particularly important purpose. It might be mildly convenient in some cases, but that's about all.
However, at this point this (mis)feature has been in place for a very long time, and I consider myself to have a responsibility not to break compatibility unnecessarily. It's at least plausible that people have unwittingly made use of it in various wrappers around man(1). (For example, Debian's lintian(1) tool includes a check that runs man(1) with various warning options enabled and reports them as problems with the package; as it turns out it does use the -l option, but it might easily not have done.) I'd be happy to try to search for potential users and file bug reports to get them changed, except that this is nearly impossible to search for. Simply making a new release that removes the feature does not meet my quality standards.
I could have it produce a warning message on stderr with an explicit deprecation. But one of the classes of wrappers around man(1) is graphical applications, and quite often nobody pays attention to their stderr. So would such a deprecation method actually be effective?
I'd welcome other suggestions that are better than "delete the feature because it's other people's fault for using it".
Thanks, -- Colin Watson (he/him) [[email protected]]
