Hi DJ, On 2026-07-14T22:34:15-0400, DJ Delorie wrote: > "G. Branden Robinson" writes: > > That link remains a good précis of the problem. One could show up my > > man(7) composition abilities and earn my gratitude by solving that > > constraint problem using only macros from the package. :) > > We already process all the raw files to fill in the date and version. The TH line is already special, so filling the date and version is relatively easy. It's in the file "share/mk/build/man/nonso.mk": $(_NONSO): $(_MANDIR)/%: $(MANDIR)/% $(MK) | $$(@D)/ $(info $(INFO_)SED $@) <$< \ $(SED) "/^\.TH /s/(date)/$$($(MANPAGEDATECMD))/" \ | $(SED) '/^\.TH /s/(unreleased)/$(DISTVERSION)/' \ | $(SED) '/^\.Dd /s/$$Mdocdate$$'"/$$($(MANPAGEDATECMD))/" \ | $(SED) '/^\.Os /s/(unreleased)/$(DISTVERSION)/' \ >$@ > Add the .in macros around .EX there? But we'd need to know where to add them. There are cases of EX/EE that don't need to be surrounded by '.in' (otfen, those that take an entire section, but also those in SYNOPSIS). Maybe we could have a full list of exceptions and write a stripy for that, but... Also, the manual pages should be readable in the form they exist in the repository (and match as much as possible how it will render when installed). That makes it easy to see if a change works, by running man(1) on the source code. If we had to build the pages before being able to read them, it would add some friction to contributors reading what they write. > There are 1528 .EX's in the tree, but a short perl script should be able > to fix them all up. Note: there are 336 .EX's that do not have the .in, I guess those are all (or most) in EXAMPLES and SYNOPSIS. > and two .EX's that do not have a closing .EE. Hmmm, indeed: $ diff -u \ <(find man/ -type f \ | sort \ | xargs grep '^\.EX$' \ | sed 's/\.EX/.EE/') \ <(find man/ -type f \ | sort \ | xargs grep '^\.EE$'); --- /dev/fd/63 2026-07-15 13:39:48.230169833 +0200 +++ /dev/fd/62 2026-07-15 13:39:48.230169833 +0200 @@ -140,7 +140,6 @@ man/man2/io_submit.2:.EE man/man2/io_submit.2:.EE man/man2/ioctl_eventpoll.2:.EE -man/man2/ioctl_eventpoll.2:.EE man/man2/ioctl_fsmap.2:.EE man/man2/ioctl_kd.2:.EE man/man2/ioctl_kd.2:.EE @@ -1460,7 +1459,6 @@ man/man7/string_copying.7:.EE man/man7/string_copying.7:.EE man/man7/string_copying.7:.EE -man/man7/string_copying.7:.EE man/man7/string_copying.7:.EE man/man7/string_copying.7:.EE man/man7/string_copying.7:.EE Hmmm, this sounds like a good linter that I should add to the build system. I can make it general for all macros that must always come in pairs. BTW, Branden, I expect this would have been diagnosed by either groff(1) or mandoc(1). Why isn't it? I've pushed a fix for EX/EE pairs. commit 4d872e2747885ee2ae6139b9bc78cc3123392b72 Author: Alejandro Colomar Date: 2026-07-15 13:42:14 +0200 man/: srcfix Add missing closing EE for EX. Reported-by: DJ Delorie Signed-off-by: Alejandro Colomar I've checked that no other pairs of man(7) macros are not balanced. $ find man -type f | xargs src/bin/lintman-pairs --- /dev/fd/63 2026-07-15 14:42:44.957949101 +0200 +++ /dev/fd/62 2026-07-15 14:42:44.957949101 +0200 @@ -668,7 +668,6 @@ man/man7/string_copying.7:.EE man/man7/string_copying.7:.EE man/man7/string_copying.7:.EE -man/man7/string_copying.7:.EE man/man7/user_namespaces.7:.EE man/man7/user_namespaces.7:.EE man/man7/user_namespaces.7:.EE @@ -1313,7 +1312,6 @@ man/man2/epoll_wait.2:.EE man/man2/epoll_wait.2:.EE man/man2/ioctl_eventpoll.2:.EE -man/man2/ioctl_eventpoll.2:.EE man/man2/landlock_restrict_self.2:.EE man/man2/sendmmsg.2:.EE man/man2/sendmmsg.2:.EE Where the script is: $ cat src/bin/lintman-pairs #!/bin/bash # # Copyright, the authors of the Linux man-pages project # SPDX-License-Identifier: GPL-3.0-or-later set -Eefuo pipefail; err() { >&2 printf '%s\n' "$(basename "$0"): error: $*"; exit 2; } if test $# -lt 1; then err "Missing files."; fi; files="$@"; check_pair() { diff -u \ <(grep "^\.$1\>" /dev/null $files | sed "/\.$1\>/s/:.*/:.$2/") \ <(grep "^\.$2\>" /dev/null $files | sed "/\.$2\>/s/:.*/:.$2/"); } check_pair 'EX' 'EE'; check_pair 'MT' 'ME'; check_pair 'RS' 'RE'; check_pair 'SY' 'YS'; check_pair 'UR' 'UE'; > Turns out Gemini is good at perl. Please don't use LLMs for contributing to this project. The file "CONTRIBUTING.d/ai" contains our guidelines for their use, which essentially says it's not allowed. > Anyway, doing this as a postprocessor would let us purge the hacks and > make .EX/.EE properly semantic again, while retaining our desired > appearance. It's also one more bit of folklore new authors won't need > to learn ;-) Have a lovely day! Alex --