Hi Branden, G. Branden Robinson wrote on Tue, Aug 15, 2023 at 10:55:22PM -0500: > If the page is withdrawn, I expect distributors will need to manage the > man.7 page using Debian's "alternatives" mechanism or similar; if > groff_man.7 is installed, man.7 should be a symlink to it. If > mandoc_man.7 is installed, likewise. If both are installed, the > distributor needs to select a default preference. I think that most general-purpose Linux distributions are probably better off simply prefering groff_man.7 over the man.7 bundled with mandoc. As you know, the mandoc distribution regards the man(7) language as a legacy language that is obsolete since about 1990 - which makes sense for all operating systems based on BSD and Illumos. Consequently, the mandoc man(7) page only provides bare-bone information focussing on questions of compatibily and no advice whatsoever for people intending to write new manual pages. That perspective is not really helpful for general purpose Linux distributions: for these, the Linux man-pages project matters a lot, and that project is not considering the man(7) language as obsolete at all. That i keep recommending changing that stance does not appear to have much effect so far and isn't relevant for the questions at hand. Either war, a disagreement regarding the merits of some policy is not a good reason to deprive users of information they might require. > I expect you will want to emphasize this in the release announcement, > when the time comes. In the Linux man-pages project release announcement, i recommend simply saying that groff_man(7) replaces the former man(7) that used to be bundled in the Linux man-pages project. For the purposes of the Linux man-pages project, the man(7) page distributed with mandoc isn't useful, so no need to confuse the users of the Linux man-pages project by talking about it. > This already needs to happen with soelim(1) and roff(7), I'm not convinced. The soelim(1) bundled with mandoc is really only a stopgap implementation in case people need something quickly but don't have a real ROFF system around. I don't think it sees much use at all. For the roff(7) manual page bundled with mandoc, the same applies as for man(7), only more strongly so. The mandoc roff(7) page is totally inadequate for learning the roff language. It merely intends to document the subset of roff(7) relevant for manual page authors and maintainers, and the subset supported by mandoc. > but it doesn't, exactly; Debian renames mandoc's versions of the > former to msoelim(1) and the latter to mandoc_roff(1). That makes sense to me, more than using "alternatives" for these two would, in the case of Debian. I'm not sure installing the mandoc soelim program on Debian is even useful in the first place. If you really need soelim(1) on Debian, you almost certainly already have groff(1) installed, or at least you ought to install it. > Termux simply throws groff's versions > away and installs mandoc's versions as soelim(1) and roff(7). That also makes some sense to me. In Termux, the complete subsystem for searching, displaying, and viewing manual pages has been exclusively based on mandoc since 2015. So while Termux is, in most aspects, more similar to a Linux distro than to a BSD system, regarding documentation, it is essentially a BSD and not a Linux system, so it totally makes sense to follow BSD conventions regarding manual page naming, installation, and manual page tools. Besides, it is a system for relatively small devices, and consequently, the decision to use BSD tools for documentation actually makes sense because the mandoc toolchain is significantly less resource- hungry than the groff toolchain. Of course, mandoc is inadequate for general-purpose typographic and publishing work - but who in their right mind would want to write their books and journal articles on Termux anyway? A small number of other Linux systems exist where similar arguments apply, most notably Alpine Linux and Void Linux. Alpine is heavily geared towards very small hardware. Void is among the Linux distros closest to BSD in philosophy. Both have been using mandoc exclusively for even longer than Termux. But even for Linux distros officially supporting that users switch their manual page search and display system from man-db+groff to mandoc if they want to - last time i looked, that included Arch, openSUSE, and Fedora - installing the mandoc roff(7) as roff(7) would seem like a bad idea to me. > I also use Termux. Imagine my surprise when I upgraded to groff 1.23.0 > on my tablet and brought up roff(7). I was expecting to see myself in > the mirror, and what should greet me but the visage of Ingo Schwarze! > > Unnerving, no? Heh, buhuuu! <evil grin> Yours, Ingo
