Hello Colin, Colin Watson wrote on Tue, Aug 26, 2025 at 06:01:47PM +0100: > 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. Makes sense, thank you for forwarding. >> -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. All of this sounds reasonable. > 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? To get started with deprecation, one might change the manual page to say, at the place where the feature is described, that it is deprecated. On might also mention it in upcoming release notes, saying that people should prepare for future removal. Admittedly, the harder part than getting deprecation started is finishing it. One could argue that explicitly deprecating it in one release, then removing it in the next, is good enough because if people rely on a program but do not read the release notes when a new release comes out, it is hard to help them. One can try to be even nicer, but when something is as hard to search for as in this case, i doubt perfection can be achieved. Two things i would do in the context of OpenBSD in a comparable case are these: 1) Ask for testing in a bulk build, i.e. in a process that builds all packages that run on the operating system. The purpose of testing in a bulk build is to catch configure-, compile-, and packaging-time problems. I suspect similar processes to build all packages in a standardized way might exist in Debian and be run regularly. I also suspect that problems of this kind will likely be mostly distribution-agnostic, making it possible to find most of them on one distro. 2) I'd probably send a heads-up to the mailing list reaching all people interested in porting software to OpenBSD, saying that if they are using software that wraps or calls man(1), they should look into whether it needs to be modified for the deprecation, and ask for my help (specifying the package in question) if needed. Such a user-/porter-centric process would aim to catch run-time issues. Given the size of the Debian project, i'm not convinced a similar all-encompassing "ports@" mailing list exists there, but you certainly know. :) > I'd welcome other suggestions that are better than "delete the feature > because it's other people's fault for using it". I will probably just delete the feature from OpenBSD and mandoc because we never documented it and never encouraged using it, and because we don't encourage wrapping man(1) either, so the risk that something breaks is likely lower than in Debian, also because our infrastructure is significantly less complicated than in Debian and contains fewer wrappers and fewer abstractions in general. Besides, if something breaks, it is easier to fix for us than in Debian because we have more frequent releases and less complicated processes. With a bit of luck, removing it from mandoc might even smoke out a few instances of problems of the kind you want to know about - though frankly, i expect minor amounts of fallout in OpenBSD, if any fallout at all. Yours, Ingo
