Re: man/man8/ldconfig.8: document system-wide tunables

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 5117 bytes --]

Hi DJ,

On 2026-07-14T22:34:15-0400, DJ Delorie wrote:
> "G. Branden Robinson" <g.branden.robinson@gmail.com> 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 <alx@kernel.org>
	Date:   2026-07-15 13:42:14 +0200

	    man/: srcfix
	    
	    Add missing closing EE for EX.
	    
	    Reported-by: DJ Delorie <dj@redhat.com>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

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

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]