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

Hi DJ,

	$ make lint-man build-catman -R -k
	make: warning: undefined variable 'GNUMAKEFLAGS'
	MANDOC		.tmp/man/man8/ldconfig.8.lint-man.mandoc.touch
	mandoc: .tmp/man/man8/ldconfig.8:212:85: STYLE: input text line longer than 80 bytes: Allow the tunable to...
	mandoc: .tmp/man/man8/ldconfig.8:250:2: WARNING: skipping paragraph macro: PP empty
	mandoc: .tmp/man/man8/ldconfig.8:270:2: WARNING: skipping paragraph macro: PP empty
	make: *** [/srv/alx/src/linux/man-pages/man-pages/contrib/share/mk/lint/man/mandoc.mk:30: .tmp/man/man8/ldconfig.8.lint-man.mandoc.touch] Error 1
	PCRE2GREP	.tmp/man/man8/ldconfig.8.lint-man.poems.touch
	lint-man-poems: .tmp/man/man8/ldconfig.8: Use semantic newlines (see man-pages(7)):
	    222:	The tunable only applies to AT_SECURE (i.e. setuid, or elevated
	make: *** [/srv/alx/src/linux/man-pages/man-pages/contrib/share/mk/lint/man/poems.mk:30: .tmp/man/man8/ldconfig.8.lint-man.poems.touch] Error 1
	make: Target 'lint-man' not remade because of errors.
	TROFF		.tmp/man/man8/ldconfig.8.cat.set
	an.tmac:.tmp/man/man8/ldconfig.8:92: style: .IR expects at least 2 arguments, got 1
	an.tmac:.tmp/man/man8/ldconfig.8:195: style: .IR expects at least 2 arguments, got 1
	an.tmac:.tmp/man/man8/ldconfig.8:197: style: .IR expects at least 2 arguments, got 1
	make: *** [/srv/alx/src/linux/man-pages/man-pages/contrib/share/mk/build/catman/troff.mk:33: .tmp/man/man8/ldconfig.8.cat.set] Error 1
	make: *** Deleting file '.tmp/man/man8/ldconfig.8.cat.set'
	make: Target 'build-catman' not remade because of errors.

	s/IR/I/

$ MANWIDTH=72 man man-pages | awk '/Use semantic newlines/,/^$/'
   Use semantic newlines
     In the source of a manual page, new sentences should be started on
     new lines, long sentences should be split  into  lines  at  clause
     breaks  (commas,  semicolons, colons, and so on), and long clauses
     should be split at phrase boundaries.  This convention,  sometimes
     known as "semantic newlines", makes it easier to see the effect of
     patches, which often operate at the level of individual sentences,
     clauses, or phrases.

	s/IR/I/

	s/IR/I/

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

Fixed.

Fixed. I think. We need a better language for this ;-)

Maybe fixed? Better at least. The linter still complains despite me splitting it up:

.B @
The tunable only applies to AT_SECURE
(i.e. setuid, or elevated capabilities)
processes.

Fixed.

I looked for ld.so.conf.5 but didn't see one (which kinda surprised me, but a lot of ldconfig isn't documented either in the man pages or in the glibc manual) so went with "what was there". I have a slight preference for "get this change in quickly" as glibc is releasing with the new funcionality soon(ish) but if you want me to split these two out, I can do that too. Or do it later.

Really, really, want a better language for this... ;-)

index ee024b8f6..19f1ddf43 100644
@@ -17,6 +17,8 @@ .SH SYNOPSIS
 .IR conf ]
 .RB [ \-r\~\c
 .IR root ]
+.RB [ \-t\~\c
+.IR tunconf ]
 .IR directory \~.\|.\|.
 .YS
 .SY /sbin/ldconfig

@@ -85,6 +87,11 @@ .SH DESCRIPTION
 .P
 Failure to follow this pattern may result in compatibility issues
 after an upgrade.
+.P
+If the file
+.I /etc/tunables.conf
+exists, it contains one tunable per line.  These tunables are stored
+in the cache and applied to every process at its startup.
 .SH OPTIONS
 .TP
 .BI \-\-format= fmt

@@ -157,6 +164,12 @@ .SH OPTIONS
 .I root
 as the root directory.
 .TP
+.BI \-t\~ tunconf
+Use
+.I tunconf
+instead of
+.IR /etc/tunables.conf .
+.TP
 .B \-\-verbose
 .TQ
 .B \-v

@@ -177,9 +190,85 @@ .SH OPTIONS
 .B \-N
 is also specified,
 the cache is still rebuilt.
+.SH INCLUDES
+The files
+.I /etc/ld.so.conf
+and
+.I /etc/tunables.conf
+allow lines to start with the word
+.I include
+followed by a path wildcard,
+and will include any files matching that wildcard.
+.SH TUNABLES
+Each line in the file
+.I /etc/tunables.conf
+specifies a tunable,
+which is a name and value separated by an equals sign.
+Each line may include zero or more words or symbols at the beginning:
+.TP
+.B overridable
+.TQ
+.B +
+Allow the tunable to be overridden by the environment variable
+(this is the default).
+.TP
+.B nonoverridable
+.TQ
+.B \-
+Do not allow the tunable to be overridden by the environment variable.
+.TP
+.B onlysecure
+.TQ
+.B @
+The tunable only applies to AT_SECURE
+(i.e. setuid, or elevated capabilities)
+processes.
+.TP
+.B nonsecure
+.TQ
+.B $
+The tunable only applies to non-AT_SECURE processes (this is the default).
+.TP
+.B anysecure
+.TQ
+.B *
+The tunable only applies to both AT_SECURE and non-AT_SECURE processes.
+.P
+The file may also contain
+.I filters ,
+which limit the tunables following it, up to the end of the file
+(or end of the included file, or start of a new included file)
+or a line with only
+.B []
+on it.  The syntax is:
+.RS
+.P
+[
+.I filter
+:
+.I pattern
+]
+.RE
+.TP
+.B proc
+The
+.I proc
+filter limits the following tunables to processes starting from the
+file matching the pattern.
+The file may be fully qualified or just the basename.
+.P
+Example config file:
+.P
+.RS
+.nf
+glibc.malloc.arenas_max=5
+onlysecure glibc.malloc.arenas_max=1
+-glibc.pthread.rseq=1
+[proc:/bin/bad.program]
+-glibc.pthread.rseq=0
+.fi
+.RE
 .SH FILES
-.\" FIXME Since glibc-2.3.4, "include" directives are supported in ld.so.conf
-.\"
 .\" FIXME Since glibc-2.4, "hwcap" directives are supported in ld.so.conf
 .PD 0
 .TP

@@ -191,6 +280,11 @@ .SH FILES
 one per line,
 in which to search for libraries.
 .TP
+.I /etc/tunables.conf
+contains a list of tunables,
+one per line,
+to apply to all newly created processes.
+.TP
 .I /etc/ld.so.cache
 contains an ordered list of libraries found in the directories
 specified in

Hi DJ,

21 years ago I figured we'd get one that would conquer the world. We haven't. Too bad. I could have started working on groff back then.

Here's a summary of how we got here.

* man(7) (Bell Labs CSRC, 1979) was "good enough" ("worse is better"). At least one generation of Unix people came up venerating the documents written using it.
* Many, many programmers don't want to _write_ documentation at all.
* Many programmers' managers regard documentation as an unwelcome friction slowing down the launch of a Minimum Viable Product.
* Many of the programmers who _do_ want to write documentation don't want to compose it in anything more complex than Markdown.
* Markdown can't do semantics.
∴ Goodbye, "semantic Web".

* People who did want a semantic Web ran into problems.
* XML overpromised and underdelivered.
* DocBook-XML was lexically overcomplicated--meaning hard to learn--with something like 400 elements. A part-time practitioner, such as a person writing in a "real" programming language, could not retain the markup language in their head between periods of exile to Documentation Land. Further, its toolchain, involving stuff like jade and opensp, was heavyweight and difficult to work with. And also written in Java because Java was going to be the One Language to Rule them All, with C and C++ forgotten, by 2005 or so.
∴ "Semantics" got a bad rap because everyone with a fat wallet who
backed it bet on a losing horse for the delivery of said semantics. They spent 10+ years telling the world that XML was the _only way to do semantics_. And because venture capitalists and tech bros are infallible geniuses in black turtlenecks, everybody believed them.

* There's mdoc(7), which one might uncharitably say brought you the worst of all worlds. Semantics? Yes! But many element types. (Only about 1/4th as bloated as DocBook, though. And Ingo Schwarze insists you can get by with much less than that. Until you guess wrong and he reviews your document. ;-) ) And if you don't like *roff as a macro system, wait until you discover mdoc! It implements a macro processor on top of your macro processor! And mdoc(7) was only created in the first place because AT&T were such jerks about the licensing of troff (and Unix generally). So the Berkeley CSRG's mandate, I infer, was to spec out a macro system that could eventually be ripped free of troff and set down on top of something else.
* That decision, taken in maybe 1987 or 1988, predated by only one year the advent of James Clark's "groff", which BSD promptly shipped in Net/2 and later 4.4BSD. (Later, its descendants ripped it out again, because GPL and C++ bad. BAD!)
* That "other" macro system didn't arrive until about 2010, in the shape of mdocml(1)--now known as mandoc(1)--which, because man(7) documents had not had the decency to shrink below 90-95% of man pages on all systems, ended up reimplementing huge chunks of...troff.
∴ Almost the only people writing mdoc(7) are strident BSD partisans.
You can write your man page in mdoc(7), but sooner or later you'll be asked why you aren't running *BSD, and you'll get treated like an idiot if you don't. You will then understand how *BSD is a refuge from the evangelicalism of GNU people.[1] ;-)

* In my estimation, TeX could have conquered this space too. It was pristinely engineered (if idiosyncratically implemented), had tons of momentum, oodles of capable practitioners, and a benign, deific, universally esteemed figure behind it.
* TeX's holy mission is beautiful typography, and it's good at it.
* People read man pages on terminals 90%+ of the time.
* You can't do beautiful typography on terminals.
* Terminals can **** off.
∴ TeX ceded this ground without ever contesting it.

I've ventured my own proposal for the addition of a flexible semantic system to man(7) with backwards compatibility, at the cost of only two additional macro names.[2] Literally no one has expressed interest.

So it goes.

Regards,
Branden

[1] mdoc(7) is fine. It has some nice features, and insofar as I have a command of it, I'm happy to help people draft or improve their man pages that use it. What it is not, is easier than man(7).

[2] https://lists.gnu.org/archive/html/groff/2022-12/msg00075.html

And roff has .IR ;-)

These days, most of the docs I write are in texinfo or HTML (raw html, not markup). I think I've experienced most of the formats on your list. I think I've written converters between many things on your list.

Is there a canonical reference to the flavor of roff that we write to, for modern systems' man page formatters?

Hi DJ,

groff_man(7) and groff_man_style(7) are what you're looking for, I believe.

Cheers,
Alex

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

Nevermind, found it...

Hi DJ,

You need to use a dummy character to tell this linter that you really meant a dot followed by one space which doesn't terminate the sentence.

(i.e.\& setuid, or elevated capabilities)

Other than that, it's better.

Also, man-pages(7) recommends using 'that is,' instead of 'i.e.,'.

$ MANWIDTH=72 man man-pages | awk '/Use of e.g.,/,/^$/'
   Use of e.g., i.e., etc., a.k.a., and similar
     In  general,  the  use  of  abbreviations  such as "e.g.", "i.e.",
     "etc.", "cf.", and "a.k.a." should be avoided, in favor  of  suit‐
     able  full  wordings ("for example", "that is", "and so on", "com‐
     pare to", "also known as").

I would very much prefer to split these out.

An incomplete ld.so.conf.5 page would be fine; we don't need to make it perfect. But the separate manual page would help keep this documentation reasonably organized.

I can help to get this quickly in.

For remembering these, IR is for alternating italics and roman, and I is for fully italics.

$ MANWIDTH=72 man man-pages | sed -n '/Indentation/,+18p'
   Indentation of structure definitions, shell session logs, and so on
     When  structure definitions, shell session logs, and so on are in‐
     cluded in running text, indent them by 4 spaces (i.e., a block en‐
     closed by .in +4n and .in), format them  using  the  .EX  and  .EE
     macros,  and surround them with suitable paragraph markers (either
     .P or .IP).  For example:

         .P
         .in +4n
         .EX
         int
         main(int argc, char *argv[])
         {
             return 0;
         }
         .EE
         .in
         .P

	.IP
	.in +4n
	.EX
	.RI [ filter : pattern ]
	.EE
	.in
or
	.IP
	.in +4n
	.EX
	.RI [\~ filter \~:\~ pattern \~]
	.EE
	.in

	$ diffman-git HEAD^^
	--- HEAD^^^:man/man4/console_codes.4
	+++ HEAD^^:man/man4/console_codes.4
	@@ -439,7 +439,7 @@ DESCRIPTION
				       to txt.
	      ESC ] 1 ; txt ST         Set icon name to txt.
	      ESC ] 2 ; txt ST         Set window title to txt.
	-     ESC ] 4 ; num ; txt ST   Set ANSI color num to txt.
	+     ESC ] 4 ; num ; txt ST   Set color num (0‐255) to txt.
	      ESC ] 10 ; txt ST        Set dynamic text color to txt.
	      ESC ] 46 ; name ST       Change log file to name (nor‐
				       mally disabled by a compile‐

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

Hi DJ,

I have added a small ld.so.conf(5) manual page (already pushed to master). This will allow you to add stuff there. If you want to add a tunables.conf(5) manual page, you can have a look at the ld.so.conf(5) page.

Cheers,
Alex

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

How about this?

index 481cf9152..aa27b73f6 100644
@@ -9,6 +9,14 @@ .SH DESCRIPTION
 This file contains a list of directories,
 one per line,
 in which to search for libraries.
+The file allows lines to start with the word
+.I include
+followed by a path wildcard,
+and will include any files matching that wildcard.
+The file is parsed by
+.B \%ldconfig
+and the results stored in
+.IR /etc/ld.so.cache .
 .SH FILES
 .I /etc/ld.so.conf
 .SH SEE ALSO

index 5f3c22ef2..40f129b71 100644
@@ -792,7 +792,8 @@ .SH FILES
 .TP
 .I /etc/ld.so.cache
 File containing a compiled list of directories in which to search for
-shared objects and an ordered list of candidate shared objects.
+shared objects and an ordered list of candidate shared objects,
+and any system-wide tunables to be applied.
 See
 .BR ldconfig (8).
 .TP

index 9ac146b44..234169504 100644
@@ -17,6 +17,8 @@ .SH SYNOPSIS
 .IR conf ]
 .RB [ \-r\~\c
 .IR root ]
+.RB [ \-t\~\c
+.IR tunconf ]
 .IR directory \~.\|.\|.
 .YS
 .SY /sbin/ldconfig

@@ -85,6 +87,13 @@ .SH DESCRIPTION
 .P
 Failure to follow this pattern may result in compatibility issues
 after an upgrade.
+.P
+If the file
+.I /etc/tunables.conf
+exists,
+it contains tunables to be applied to all processes.
+These tunables are stored
+in the cache and applied to every process at its startup.
 .SH OPTIONS
 .TP
 .BI \-\-format= fmt

@@ -157,6 +166,12 @@ .SH OPTIONS
 .I root
 as the root directory.
 .TP
+.BI \-t\~ tunconf
+Use
+.I tunconf
+instead of
+.IR /etc/tunables.conf .
+.TP
 .B \-\-verbose
 .TQ
 .B \-v

@@ -178,8 +193,6 @@ .SH OPTIONS
 is also specified,
 the cache is still rebuilt.
 .SH FILES
-.\" FIXME Since glibc-2.3.4, "include" directives are supported in ld.so.conf
-.\"
 .\" FIXME Since glibc-2.4, "hwcap" directives are supported in ld.so.conf
 .PD 0
 .TP

@@ -190,11 +203,17 @@ .SH FILES
 See
 .BR ld.so.conf (5).
 .TP
+.I /etc/tunables.conf
+See
+.BR tunables.conf (5).
+.TP
 .I /etc/ld.so.cache
 contains an ordered list of libraries found in the directories
 specified in
 .IR /etc/ld.so.conf ,
-as well as those found in the trusted directories.
+as well as those found in the trusted directories,
+and any system-wide tunables listed in
+.IR /etc/tunables.conf .
 .PD
 .SH SEE ALSO
 .BR ldd (1),

Hi DJ,

Please split into separate patches with commit messages, and send one email per patch (the usual git-format-patch(1) + git-send-email(1) would work).

	.P

	.P

	.P

	.P

	.BR \%ldconfig (8)

	.IP
	.in +4n
	.EX
	.RI [ filter : pattern ]
	.EE
	.in

	\-

	\-

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

How do you want them split? Per man page, or one for breaking out ld.so.conf and one for adding tunables.conf?

Also, I've been using the output of "git show" for these patches.

We still need a better language ;-) ("why doesn't it know to start a paragraph after a heading?" ;)

.P
The syntax allows lines to start with the word
.I include
followed by a path wildcard,
and will include any files matching that wildcard. The wildcard is a path specification in the
.BR \%glob (7)
format.
Files matching that wildcard will be processed
as if their contents were included in the main config file.

Fixed.

Fixed.

Fixed, but that's a lot of one-sentence paragraphs.

Fixed.

No, the environment variable is read at runtime, not by ldconfig.

a set-user-ID program. Fixed.

Isn't that what the .IP does ?

It actually means exactly what it says, but I admit it can be confusing. When the dynamic linker creates a process, and uses the image in file /file/ as the template, that new process is affected.

i.e. If you type "/usr/bin/ls" and the filter is "/usr/bin/ls", that new copy of /usr/bin/ls is affected.

No, for security and logical reasons, it cannot be a relative path. So you end up with "one specific version of XYZ" or "any version of XYZ". No wildcards either. It's intended for rare exceptions.

commit a9b49369175e67e07b556ec28cd2d9d5538c0fe6

Author: DJ Delorie <[email protected]>
Date:   Mon Jul 13 17:30:56 2026 -0400

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

index 481cf9152..9954c74bc 100644
@@ -6,9 +6,36 @@ .SH SYNOPSIS
 .B /etc/ld.so.conf
 .fi
 .SH DESCRIPTION
+.P
 This file contains a list of directories,
 one per line,
 in which to search for libraries.
+.P
+The file
+(and any other files included by it)
+is parsed by
+.B \%ldconfig
+and the results stored in
+.IR /etc/ld.so.cache .
+.P
+The syntax allows lines to start with the word
+.I include
+followed by a path wildcard,
+and will include any files matching that wildcard.
+The wildcard is a path specification in the
+.BR \%glob (7)
+format.
+Files matching that wildcard will be processed
+as if their contents were included in the main config file.
+.P
+Example config file:
+.IP
+.EX
+/lib
+/usr/lib
+/usr/local/lib
+include /etc/ld.so.conf.d/*.conf
+.EE
 .SH FILES
 .I /etc/ld.so.conf
 .SH SEE ALSO

index 5f3c22ef2..40f129b71 100644
@@ -792,7 +792,8 @@ .SH FILES
 .TP
 .I /etc/ld.so.cache
 File containing a compiled list of directories in which to search for
-shared objects and an ordered list of candidate shared objects.
+shared objects and an ordered list of candidate shared objects,
+and any system-wide tunables to be applied.
 See
 .BR ldconfig (8).
 .TP

index 9ac146b44..234169504 100644
@@ -17,6 +17,8 @@ .SH SYNOPSIS
 .IR conf ]
 .RB [ \-r\~\c
 .IR root ]
+.RB [ \-t\~\c
+.IR tunconf ]
 .IR directory \~.\|.\|.
 .YS
 .SY /sbin/ldconfig

@@ -85,6 +87,13 @@ .SH DESCRIPTION
 .P
 Failure to follow this pattern may result in compatibility issues
 after an upgrade.
+.P
+If the file
+.I /etc/tunables.conf
+exists,
+it contains tunables to be applied to all processes.
+These tunables are stored
+in the cache and applied to every process at its startup.
 .SH OPTIONS
 .TP
 .BI \-\-format= fmt

@@ -157,6 +166,12 @@ .SH OPTIONS
 .I root
 as the root directory.
 .TP
+.BI \-t\~ tunconf
+Use
+.I tunconf
+instead of
+.IR /etc/tunables.conf .
+.TP
 .B \-\-verbose
 .TQ
 .B \-v

@@ -178,8 +193,6 @@ .SH OPTIONS
 is also specified,
 the cache is still rebuilt.
 .SH FILES
-.\" FIXME Since glibc-2.3.4, "include" directives are supported in ld.so.conf
-.\"
 .\" FIXME Since glibc-2.4, "hwcap" directives are supported in ld.so.conf
 .PD 0
 .TP

@@ -190,11 +203,17 @@ .SH FILES
 See
 .BR ld.so.conf (5).
 .TP
+.I /etc/tunables.conf
+See
+.BR tunables.conf (5).
+.TP
 .I /etc/ld.so.cache
 contains an ordered list of libraries found in the directories
 specified in
 .IR /etc/ld.so.conf ,
-as well as those found in the trusted directories.
+as well as those found in the trusted directories,
+and any system-wide tunables listed in
+.IR /etc/tunables.conf .
 .PD
 .SH SEE ALSO
 .BR ldd (1),

It does.

groff_man(7):

.SH [heading‐text]
Set heading‐text as a section heading. Given no argument, SH plants a one‐line input trap; text on the next line becomes heading‐text. The heading text is set in bold (or the font specified by the string HF), and, on typesetters, slightly larger than the base type size. If the heading font \*[HF] is bold, use of an italic style in heading‐text is mapped to the bold‐italic style if available in the font family. The inset level is reset to 1; see subsection “Horizontal and vertical spacing” below. Text lines after
^^^^^^^^^^^^^^^^
the call are set as an ordinary paragraph (P). ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There were difficulties, some imposed by the previous Linux man-pages maintainer, Michael Kerrisk.

https://lore.kernel.org/linux-man/[email protected]/

The better language that doesn't yet exist would, of course, solve all of everyone's problems at once, even the problems that are mutually exclude each other's solutions.

Regards,
Branden

[self-follow-up]

I worded that sentence like crap, and threw shade on Michael when I didn't mean to. There was a very pretty _constraint problem_ that Michael posed to me--one I was unable to solve. Sorry, Michael!

I sympathize with the problem, and don't often endorse "punching through the floor" to employ "raw" *roff requests in a man(7) document, but this was an exception. The Linux man-pages corpus is huge; Michael then and Alex now have a large management challenge, so it's reasonable to facilitate shuffling EX/EE examples from place to place in that corpus with simple copy-and-paste operations.

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. :)

Alternatively, if I think of a backward-compatible extension I can add to groff man(7) that would eliminate the need for these in requests, I'd likely implement it. I welcome design suggestions!

I should not send mails after a 12-hour session preparing a release candidate...

Regards,
Branden

We already process all the raw files to fill in the date and version. Add the .in macros around .EX there?

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, and two .EX's that do not have a closing .EE.

Turns out Gemini is good at perl.

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 ;-)

Hi DJ,

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)/' \
	>$@

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.

I guess those are all (or most) in EXAMPLES and SYNOPSIS.

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 <[email protected]>
Date: 2026-07-15 13:42:14 +0200

man/: srcfix

Add missing closing EE for EX.

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';

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.

Have a lovely day!
Alex

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

Ok, now you have a new rule that's even easier to not know about :-P

Not a problem here, a different indentation doesn't affect readability.

Er, close? ;-)

Is ".in +4n" the default for .EX, unless the user changed it? I wonder how often that case comes up. I wonder because I would need to review an example of the problem to figure out how to search for it ;-)

Now I wonder if the problem case is predictable enough to have the preprocessor *know* when .EX needs the .in +4n, and when it doesn't...

Yup, I have my own lman script that acts like man(1) but takes a filename instead of a man page reference, finds it in the tree, and formats it with underscores, italics, bold, *and* color!

Perhaps such a helper could be included in the git repo, just for authors?

None of the patches I've sent include anything AI-generated, nor would I attempt such a thing without disclosure, because I understand and agree with the legal and quality issues of AI-generated output. However, I won't not use AI to help me understand the problems I'm trying to solve, or optimize any diagnosing I need to do. My time is too precious to be stupid on purpose.

What I did was tell Gemini what I was looking for, and it wrote a perl script faster than I could open my editor. Cut, paste, run, throw it away. That was just for the statistics, of course. If we added a preprocessor script to the build itself, then (1) I wouldn't use AI, and
(2) it would be sed instead of perl anyway, to avoid another dependency.

Ok, now I looked for it, and we *already* use a perl script to preprocess the files, in scripts/mk/build/pdf/book/prepare.pl. (this just means perl is not a new dependency, so we *could* use perl instead of sed)

glibc is the same way, I'm used to that.

However, glibc decided that it has no place dictating how the user uses AI *outside* of creating the patch itself. Yes, that includes linters, analyzers, and perl scripts that generate statistics so I can understand what I'm working on.

I refuse to follow any policy that tells me what my morals should be in the privacy of my own home.

Hi DJ,

The man(7) package doesn't impose a rigid stylesheet on its output. Many decisions about presentation and layout have to be made at the project level. Historically, there have been, for example, many differences of opinion over whether items like file names, environment variable names, function names, data types, parameters to functions, and names of other man pages should be set in roman, bold, or italic.

One solution to this problem is to come up with an element name for every distinguishable syntactical item of interest. That's how DocBook-XML ended up with something like 400 tags. Granted, its scope was intended to be an entire camera-ready technical book, like one in the O'Reilly Nutshell series. *roff macro packages for man pages have a narrower scope. Thus, the "semantic" mdoc(7) package has a mere ~100 macro names, including gems like the following.

groff_mdoc(7):
.Ot Usage unknown. The mdoc sources describe it as “old function
type (fortran)”.

.Fr is an obsolete means of specifying a function return value.

Usage: .Fr return‐value ...

‘Fr’ allows a break right before the return value (usually a single digit) which is bad typographical behaviour. Instead, set the return value with the rest of the code, using ‘\~’ to tie the return value to the previous word.

Its default width is 12n.

.Me Usage unknown. The mdoc sources describe it as a macro for
“menu entries”.

Its default width is 6n.

The only alternative I know of to not exhaustively cataloging every type of "thing" one might use to compose a man page is to write down rules governing the usage of a smaller lexicon, which itself is necessarily semantically "loose", and thus frequently derided as "presentational".

There is, potentially, a _third_ option, which I mentioned in my earlier email. As I said, literally no one expressed interest.

https://lore.kernel.org/linux-man/[email protected]/T/#m9fda91ba28ca257c67d4595f81d38b32c5c9c937

No, meddling with indentation is not part of EX's job at all.

groff_man(7):
.EX
.EE Begin and end example. After EX, filling is disabled (and,
on typesetters, a monospaced font family is selected). Calling EE enables filling (and restores the previous family).

Ninth Edition Unix introduced the EX and EE extensions. Documenter’s Workbench (DWB), Heirloom Doctools, and Plan 9 troffs, and mandoc (since 1.12.2) support them. Solaris troff does not.

It wouldn't be hard to snapshot a text dump of all the man-pages project's documents, as with "nroff -t -mandoc", do a "sed -i '/^\.in/d' man/man*" over the tree, snapshot another dump, and study the diff.

It's the sort of thing I'd try out were I on a mission to eradicate in request usage from the man-pages project's documents, but I have no such mission.

What preprocessor?

That script is used just to generate a PDF of one or two man page corpora. Deri James and Brian Inglis participate in groff development. (Deri is the author of gropdf(1).) The script is there to get older versions of groff "over the hump" while we implemented PDF and hyperlinking support directly within groff itself. (That work was substantially delivered in the groff 1.23 release in July 2023; note the script's date of December 2022.) I see that it also has some features to stylistically massage Research Tenth Edition Unix man pages.

"prepare.pl" is not a general-purpose preprocessor that can or should be run over a given document in the Linux man-pages. As I understand it, one of Alex's objectives, as was Michael's before, is to keep the files in the man/man* directories directly renderable with "man -l".

Regards,
Branden

Perhaps, but the fact that I now know about the rule, and the exception, means that it's not entirely flexible either ;-)

In this case, it does sound like the man pages need a different thing for "example code" (.EX) and "preformatted text" (html's <PRE>). Or we need some magic for known types of .SH like SYNOPSIS which are almost always rendered differently than other sections.

glibc uses texinfo, which is TeX but terminals don't have **** off ;-)

I think of texinfo as a "TeX compiler". I don't write programs in assembly either (well, usually ;).

I've always advocated for "whatever system means the docs are stored and edited with the code, that I can turn into whatever I need." Roff, html, texinfo, markup, whatever. I know how to write converters. DJGPP had a rule about "every .c must have a .txh" where the .txh was a texinfo snippet, and these had meta-info in them so the tools knew where to put them in the manual. gEDA's pcb had a "comments in code become manual" system that used a short perl script to merge everything. Etc.

Yes, I know why the man pages are separate. I've advocated for the glibc project to maintain its man pages along with the sources that affect them, but it's easier to just have glibc developers be man page contributors too. I wrote the tunables docs a long time ago, but had to hold back the patch until I knew which release would have the code changes, so they would stay in sync.

Nor do I, but I wondered if there was a programmatic way to automate this so that the authors don't need to worry about it. My general rule is "the third time you repeat something, automate it." I still don't have a robot lawn mower, though ;-)

Whatever "sed" scripts we run in the Makefiles, that's all. Currently they just fill in the .TH data.

I agree with that!

I just think we could relax the "and must be formatted exactly as a release" a bit, in exchange for making it easier to contribute by removing one or two rules the contributors need to know.

But that assumes that it's (1) purely cosmetic, and (2) automatable. I note that "man" formats according to the window's width, so even the official tools don't honor the "and formatted exactly as" rule.

(wait, when did "man -l" happen? Have I been missing that all along? Is my script really that old?)

Hi DJ,

The man(7) macro language is not highly flexible, no, but it didn't need and wasn't meant to be. If you punch through the floor to raw *roff, you can acquire some pretty impressive flexibility, but then draw the ire of the people who write non-*roff interpreters of man(7). At some point in the 1990s, a bunch of Linux people got the notion that man(7) was a markup language like HTML, and started writing a variety of translators for it, all called "man2html".[0]

Some had little success, others a bit more, but all eventually dashed themselves on the rocks of a man page that is more ambitious than they had planned for.

In groff_man_style(7), I urge authors to limit themselves to only the (non-deprecated) macros of the man(7) package and a small subset of *roff escape sequences in an effort to keep the peace among those using *roff formatters, mandoc(1), and man2html and other scrapers and ad-hoc translators. That effort in turn serves the goal of making man page text accessible to as many readers as possible, because it's hard enough getting programmers to write that documentation, in _any_ language, in the first place.

We have other objectives for man(7) too, like being able to also render a publication-quality PDF with a useful navigation pane and hyperlink support, both internally and externally.

A common error is to assume that EX implies <PRE>. It doesn't.

groff_man_style(7):
... An example region is not a “literal mode” of any sort:
special character escape sequences must still be used to produce correct glyphs for ', -, \, ^, `, and ~ (see subsection “Portability” below). Sentence endings are still detected and supplemental inter‐sentence space applied. If the amount of supplemental inter‐sentence spacing is altered, the rendering of, for instance, regular expressions using . or ? followed by multiple spaces can change. Use the dummy character escape sequence \& before the spaces.

We _can_ render them differently. _We have the technology._

Synopsis macros
Use SY and YS to summarize syntax using familiar Unix conventions. Heirloom Doctools troff (since Git snapshot 151218) and mandoc (since 1.14.5) support these GNU extensions; DWB, Plan 9, and Solaris troffs do not.

.SY keyword [suffix]
Begin synopsis. Adjustment and automatic hyphenation are disabled. If SY has already been called without a corresponding YS, a break is performed. keyword and any suffix are set in bold. When suffix is present, the package sets the next word after it without intervening space. If a break is required in subsequent text (up to a paragraphing, sectioning, or YS macro call), lines after the first are indented. Unless the previous synopsis’s indentation is reused (see YS below), output lines after the first indent by the width of the pending output line up to the end of keyword plus a space, if keyword is the only argument, and up to the end of suffix otherwise.

.YS [reuse‐indentation]
End synopsis, breaking the line and restoring indentation, adjustment, and hyphenation to their previous states. If an argument is given, the indentation corresponding to the previous SY call is reused by the next SY call instead of being computed.

But, for those who don't want to employ these extensions, in groff 1.24.0 I undeprecated the HP macro (a decision made by Eric Raymond in about 2008, I think).

.HP [indentation]
Set a paragraph with a hanging indentation. Text on output lines after the first is indented by indentation, if specified, and by the amount of the IN register otherwise.

Caution: A hanging indentation cannot be expressed naturally in (pure) HTML, a hanging paragraph is not distinguishable from an ordinary one if it formats on only one output line, and non‐roff‐based man page interpreters may treat HP as an ordinary paragraph anyway. Thus, information or distinctions you mean to express with indentation may be lost.

At long last I've started working on the CSS stylesheet groff produces,[1] and I expect to finagle up a provision for paragraphs with hanging indents, since several macro packages, not just man(7), support them. It's simply not an urgent matter. I'd like to get groff 1.25.0 out soon.

Yes. And info(1) sometimes produces...intriguing results.

1.6 Output Devices
==================

GNU 'troff''s output is in a device-independent page description language.

...

Delimiter syntax is flexible (and laborious to describe) primarily
for historical reasons; the foregoing restrictions need be kept in mind mainly when using GNU 'troff' in AT&T compatibility mode. Normally, GNU 'troff' keeps track of the nesting depth of escape sequence interpolations, so the only characters you need to avoid using as delimiters are those that appear in the arguments you input, not those that result from interpolation. Typically, ''' works fine.(4) (*note Delimiters-Footnote-4::)

Is the neutral apostrophe of syntactical import in the language you're documenting with Texinfo? Tough.

I guess there is a Law of Conservation of ****ing Off.

That's an excellent way to think of it. TeX and troff are both Turing-complete languages.

No indeed. The real "assembly language" of troff is its "device-independent output", which for short I call "trout" if it's Kernighan's original spec from CSTR #97 in 1982, or "grout" if it features groff's extensions.

Here's an example from a test script I have, in shell, for grotty(1).

input='#
x T ascii
x res 240 24 40
x init
p 1
x font 1 R
f 1
s 10
V 40
H 0
m d
D F d
t 1234567890123456
n 40 0
V 80
H 0
t abcdef
w
h 48
t ijklmnop
n 40 0
V 120
H 0
t abcdefg
w
h 24
t ijklmnop
n 40 0
x trailer
V 120
x stop
#'

That's a good idea. And Pandoc can help where knowledge is lacking.

I've soured completely on the notion of a uniform documentation format for all domains. We've seen world conquerors come and go across multiple generations. They either give up, or proclaim that the limitations of their selected champion are not really limitations at all, and that everyone else is stupid to complain.

Again, _that people write useful documentation at all_ is my primary concern. I decided that I could be of aid in keeping groff and man(7) fit for purpose, when one's already decided those are the tools they're going to use, or the project they work with has decided for them.

Yup. Done well, literate programming is wonderful!

At one time, Texinfo was one of those world conquerors. Like groff, it had a stretch where it went nearly completely moribund. (Actually, groff had more like two of those.)

You have more patience than I do, then. The _second_ time I find myself doing something manually, I start writing a script, and spend much more time refining it than I would have just doing the tedious thing again. But I have more fun, and if I have to undertake the noxious task a third time, I'm ready. :)

Chaotic environments mess up our automatons. Trash blows into the yard (or is discarded there by neighbors). Wildlife learns to screw with the machine.[2] Or a contributor brings you a present.[3]

Indentation revision, and wholesale request (or macro call) insertion, seems like a job of slightly greater magnitude.

Yes, but people get _really wedded_ to the specifics of rendering even after setting aside the huge issue of terminal width. The podlators maintainer, for example, has exacting expectations about the widths of paragraph indentations, a parameter that has been tunable at rendering time _since 1980_.

groff_man(7):

Options
...
-rIN=standard‐indentation
Set the default indentation amount used by IP, TP, and HP, and the inset amount used by RS. The default is 7n on terminals and 7.2n on typesetters. Use only integer multiples of unit “n” on terminals for consistent indentation.
...
History
...
UC appeared in 3BSD (1980). Unix System III (1980) introduced P and exposed the registers IN and LL, which had been internal to Seventh Edition Unix man. ...

In the man-db implementation of man(1), it seems to date back to _at least_ 2002, as I see a Git commit for it (imported from CVS or Subversion or something) mentioning it as an already existing feature.

commit 5ca206194b7bda56d1d4cbfb0a9ee401c5ea9a7b

Author: Colin Watson <[email protected]>
Date:   Sun Sep 14 15:58:58 2003 +0000

* src/encodings.c (get_source_encoding): Assume ISO-8859-1 source encoding if it's unknown (e.g. 'man -l'). (get_default_device): source_encoding can no longer be NULL.
* src/man.c (make_roff_command): Likewise.

If you are/were using Red Hat/RPM-based systems, you may have been using Brouwer/Lucifredi man(1), which as far as I know never implemented this -l option. After that implementation lay moribund for many years, Fedora threw in the NIH towel in, apparently, 2010.[4]

Regards,
Branden

[0] https://invisible-island.net/scripts/man2html.html#same-name
[1] https://lists.gnu.org/archive/html/groff-commit/2026-07/msg00096.html

    https://lists.gnu.org/archive/html/groff-commit/2026-07/msg00098.html

[2] https://www.reddit.com/r/Unexpected/comments/9hek1m/like_a_boss/
[3] https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1
[4] https://pagure.io/fork/evana/fedora-comps/c/fb4ab73d9eff9f06330bc8cb6fdaba9a0b418bcc?branch=0231a510e78ca62533cdd473914bba725050c85a

Sorry, I meant the man-pages style guide rules, not roff itself.

I just meant for semantic context, like "this is a code snippet" vs "I want this to be formatted the way I typed it." Might be helpful when outputting HTML/CSS, like the examples would be in boxes and shaded with the usual "copy to paste buffer" button, but <pre> would just be monospaced and unformatted. But thus is the slippery slope that led to XML, and we don't want that again.

My preference here is PDF, as we make sure all the cross refs and TOC work correctly, and it formats very nicely (duh, TeX). Info is useful in emacs only because my fingers are already on the keyboard.

I've been accused of abusing my own namespace here. I would have called my version "djrout".

I once worked for a guy who, at one point, wrote a typesetter that went between satellites and the New York Times. The typesetting had to be perfect, every time, and run at line speed. I learned a lot from him, and he's the reason I have my own copy of the Chicago Manual of Style and know what Reverse Boustrophedon is.

Also, Team Oxford Comma!

I might predate even that.

RHEL 9 has "man -l" via man.man-db at least, but that's today.

Hi DJ,

On 2026-07-15T14:19:49-0400, DJ Delorie wrote:
[...]

I find it easier to write documentation in man(7) than in any other languages. It's simple enough that I don't need to remember much. Also, not needing to compile the documentation makes it also easier to deal with. I don't write assembly, but sh(1) scripts are nice for writing something quick. :)

If you mean store them in a separate file (such as a .3 file next to the .c file), I can agree.

If you mean source code comments (that is, in the same file), I disagree. I find code without comments to be more readable (assuming the author of the code doesn't golf, or worse).

[...]

You're welcome to send the patches well before they're merged in glibc. We can review them with enough time. You can just tell me the feature is not merged in glibc, and thus I can't merge.

[...]

For the tests in the build system, I use MANWIDTH=80, precisely to maintain a consistent width that is the most common one.

	$ grepc -xmk MANWIDTH share/mk/
	share/mk/configure/build-depends/man/man.mk:MANWIDTH ?= 80

It seems to be there already in the first commit of the man-db.git repository.

	190b315e1cae (2001-04-26; "Initial revision")

The ChangeLog has some older traces from it:

Wed Nov 16 20:34:54 GMT 1994 Wilf. ([email protected])

* Version: 2.2a7

* src/man.c (format_and_display_file): Fix bug which caused `man -l -' to fail. Produce sensible error message when -l file is inaccessable. Allow compressed manual pages to be specified when using -l (must have correct extension)

* soelim/soelim.l (main): ensure (progname) is the basename of argv[0] .

* src/manpath.c (main): remove local declaration of (quiet). add `--global' option.

So, it's at least as old as 1994. :)

Have a lovely night!
Alex

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

I can say the same for HTML, because I'm used to it and I stick to simple constructs. It's good that there are people who find man(7) easy, and it's good that those people have found a way to contribute using their expertese. I.e. Thank You :-)

I don't mean that.

I don't mean that either.

I mean "anything that means one commit has code change and doc change". I don't care about the mechanism. Do it either way as long as you do something.

Er, I've been working on tunables for about 3-4 years now. I doubt you'd want to hold on to a patch set that long.

In this case, the timing was poor - it finished up just before a release cycle, so whether the man pages needed to be done now or in six months was not known until the last minute. The time from glibc freeze to glibc release is plenty long enough for a man page review cycle, though.

I don't think I've had a default with of 80 for a couple decades now. I wish we'd standardized on the 132-column terminals instead.

Um, my career predates that too. I don't think I was doing man pages back then, though.

Hi DJ,

Thanks! :-)

[...]

I see; that makes sense. In general, I agree; in this specific case, I prefer it split, for other reasons, but yep.

I would be happy to review a patch until it's fine, discard it locally, and let you re-send it in 4 years (bonus points if it's In-Reply-To the original one, so I can keep track of the history easily).

Ok.

I have a big screen, and when I switched to it, I thought I could use more columns. What ended up happening is that I've increased the font size to keep my eyes healthy. :D

If I split my screen in two (which I often do), the terminal has 88 columns. Considering that I enable column numbers in vim(1), I still get to use around 80 columns for actual work.

Heh!

Cheers,
Alex

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

Hi DJ,

It's not that they don't need to be surrounded, but rather that they must be not surrounded, actually.

An example is the SNOPSIS of timeval(3type):

	$ man -w timeval | xargs mansect SYNOPSIS;
	.lf 1 /usr/local/man/man3type/timeval.3type
	.TH timeval 3type 2026-02-08 "Linux man-pages 6.18-154-g618fb5732fc4"
	.SH SYNOPSIS
	.EX
	.B #include <sys/time.h>
	.P
	.B struct timeval {
	.BR "    time_t       tv_sec;" "   /* Seconds */"
	.BR "    suseconds_t  tv_usec;" "  /* Microseconds */"
	.B };
	.EE

We certainly don't want to indent that, but we want it to be monospaced, so that the fields are aligned (in PDF, PS, and HTML).

	$ man -w timeval | MANWIDTH=64 xargs mansectf SYNOPSIS | cat;
	timeval(3type)                                   timeval(3type)

	SYNOPSIS
	     #include <sys/time.h>

	     struct timeval {
		 time_t       tv_sec;   /* Seconds */
		 suseconds_t  tv_usec;  /* Microseconds */
	     };

	Linux man‐pages 6.18‐15... 2026‐02‐08            timeval(3type)

EX/EE should not try to indent stuff, since indentation is not always appropriate (even if we try to minimize differences/inconsistencies).

More than readable; I think it's a feature that the page is exactly the same as what users will read in their computers. That allows contributors to look at what they've written, and know if it makes sense or not. If they had to build it to see slight differences, I expect many would complain.

When inserted in the middle of running text, we indent the examples. The main reason is that because terminals use monospaced fonts everywhere, it's difficult to differentiate examples from the rest of the page. The 4-n indentation makes them stand out.
In PDF or HTML, because running text uses proportional fonts, the examples stand out on their own by being monospaced.

However, when not inserted in the middle of running text, that indentation is not useful, and is even ugly. Thus, we don't indent in those cases. Most often, this happens in SYNOPSIS and EXAMPLES.

I expect I would be able to write a script that differentiates them. However, as I said, I believe it's better to have the source match excatly what is installed (ignoring details in the title heading (TH)).

man(1) also accepts a path.

	$ MANWIDTH=64 man man/man5/proc_driver.5 | cat
	proc_driver(5)        File Formats Manual        proc_driver(5)

NAME
/proc/driver/ - empty dir

DESCRIPTION
/proc/driver/
Empty subdirectory.

SEE ALSO
proc(5)

Linux man‐pages (unreleased) (date) proc_driver(5)

I'd be interested in at least having a look at it! It might have something useful.

BTW, what's the etymology of 'lman', out of curiosity?

Thanks!

(I'll paste this below to reply.)

As long as it's for statistics, I won't complain (I mentally might, because the ethical concerns remain, but not publicly, because it's not my business), as statistics are not a contribution (at least in this case). I might actually doubt the statistics, though, so a disclaimer of use would be appropriate even for statistics, but as long as it isn't something that influences in a decision (for example, in merging or rejecting a patch), it's _relatively_ okay.

I would like to avoid another perl script. That one exists because its author wrote it in perl, and I don't understand perl enough to translate it to something I'd understand and be able to maintain.

If anyone understands perl enough to translate that into a shell script, I'd appreciate it very much. :)

I don't mind having perl as a dependency, but I worry about being able to maintain all the code in the repository, and that existing perl script is the one little thing I'm unable to maintain. (Every time a problem shows up, I need to contact the author.)

Nice to hear that glibc doesn't allow AI!

I'll go with a real case here, although I won't be specific in details, because I don't remember all of them, and also because it has happened several times in several projects, so this is generic enough. In some other project, a co-maintainer saw a bug report from an AI tool, and immediately wrote a fix for it. The bug report was bogus, and prompted the programmer to write a patch that indeed made the code worse. I'm very worried about this kind of problems when using AI for linting code.

Linters directly or indirectly influence the patch, even if they don't generate the patch verbatim.

Because the world has survived without AI for so many years, I think it's safer to err on the side of not using it enough, compared to using it too much.

[pasted again:]

I'm worried that I must insist on the policy in this regard. If the LLM makes you misunderstand something, and causes a false sense of understanding, your contribution might end up having lower quality than it would.

I offer my help explaining any doubts you may have, if that helps you reduce any time consumption.

I don't care about your morals in the privacy of your home. But I care about the difference between the quality of a patch, and the quality perceived by the author, and my expectations of the contributor.

Cheers,
Alex

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

I'll append it here for posterity. It's not much.

"local man page" vs installed man page.

I did too, and modified the script to show me the uncommon lines so I could verify it was doing what it was supposed to be doing.

Heh ;-)

I do, and perl looks like the right choice for that one. Perhaps in the future, if it needed maintaining, I could go through and add copious comments. For now I'm inclined to just leave it ;-)

Perl is just a shell script, for AWK, right? And AWK is just a shell script for SED? <ducks>

Well, for legal and technical reasons, not for moral reasons. The FSF's stand is similar at the moment - the legal landscape is still too risky to allow direct contributions derived from AI output. There is no moral problem with AI itself, just the way that companies have implemented it so far. If you had an AI based on FLOSS sources, run on local hardware, trained on known copyright-safe inputs, there would be no moral issue with it. Home assistant's Piper/Kaldi/HassIL modules are examples of "moral AI".

I hate those, especially when the submitter hasn't bothered to check the AI's work. However, AI *has* found some serious bugs (and sometimes with correct patches) for us. It needs to mature, but I think it is already showing it's worth.

Yes, but there's no technical solution for stupid. A contributor who is inexperienced enough to misuse AI is no different than a contributor who is inexperienced enough to misuse emacs. It's our job to help them become better contributors.

The same could be said of any technology, all the way back to the invention of farming ("hunting and gathering is good enough for everyone!")

I think the key today is to find out what it *is* good for, and what it isn't, and try to help the community find AI's place in things. In my case, I find it very useful as an "idea generator". I give it the basics of a problem and see which rabbit holes it goes down that I haven't considered yet. It's also a much better search engine than the search engines (I used it to find out about the groff_man man page). However, I treat it like "a recent college grad with a degree in Everything." Knowledge but not wisdom, needs oversight.

In our specific case, I wouldn't want AI to write mission-critical software, but it's a waste of my time to write yet another single-use 20-line perl script to look for patterns in man pages. Plus, I didn't ask the AI to give me the statistics, I asked it for the perl script. It's short enough I can look at it and say "yup, that's what I would have written", and then *I* run it to get the statistics.

(as an amusing aside, our company encourages us to use AI to automate boring repetitive tasks. So I had it do my quarterly self-review. I think it did a better job than I would have at making me look good...)

This is not an LLM problem. EVERYTHING we use to help us solve problems could lead to misunderstanding. I *know* AI can be wrong, and I double check it all the time. Please give me some credit for my many decades of not trusting technology ;-)

Then judge the patch, help the author/contributor improve, and not worry about the hidden details. You don't make the author use a specific editor, or a particular brand of keyboard. AI is just another tool. Yes, we should not accept *unmoderated* AI contributions, but how a human chooses to use the tools available to them is up to them, not us.

--------------------------------------------------
#!/usr/bin/perl
# -*- perl -*-

$MANPATH=$ENV{"MANPATH"};
$MANPATH=".:/usr/local/man";

if ($#ARGVV == 1) {
    $pattern = "^$ARGV[1]\\.$ARGV[0]" . "\\D*";
} else {
    $pattern = "^$ARGV[0]" . "\\.(\\d\\D*|[a-zA-Z]\$)";
}

# print "pattern is $pattern\n";

if ( -f $ARGV[0] ) {
    $page = $ARGV[0];
} else {
    # Find it, including one level of subdirectory.
  DIR:
    for $dir (split(':', $MANPATH)) {
	opendir(D, $dir);
	for $f (sort readdir(D)) {
	    next if $f =~ /^\./;
	    #print "try $dir/$f\n";
	    if ($f =~ m@$pattern@io) {
		$page = "$dir/$f";
		last DIR;
	    }
	    if ( -d "$dir/$f") {
		opendir(SD, "$dir/$f");
		for $sf (sort readdir(SD)) {
		    next if $sf =~ /^\./;
		    #print "try $dir/$f/$sf\n";
		    if ($sf =~ m@$pattern@io) {
			$page = "$dir/$f/$sf";
			last DIR;
		    }
		}
		closedir(SD);
	    }
	}
	closedir(D);
    }
}

unless ($page) {
    print "Not found!\n";
    exit 0;
}
# print "Found $page\n";
# exit 0;

# Get the terminal's width
$stty = stty size 2>/dev/null;
($height, $width) = ($stty =~ m@(\d+)\s+(\d+)@);
$width = $width unless $width > 10;
$width -= 2;

# I prefer no hyphenation when I'm reviewing my changes $hypenate = "";
#$hyphenate = "-rHY=0";

open(N, "groff -mandoc -Tutf8 -rLL=${width}n $hyphenate -rCR=1 -P-i $page |"); #open(M, "| less -R");
#select M;

while (<N>) {
    # Colorize certain formatting
    s/\033\[1m/\033\[1;32m/g;		# bold -> green
    s/\033\[3m/\033\[3;34m/g;		# italics -> blue
    s/^\033\[1;32m/\033\[1;31m/g;	# section headers are red

    s/\033\[21m/\033\[21;39m/g;		# ending style ends color too
    s/\033\[22m/\033\[22;39m/g;
    s/\033\[23m/\033\[23;39m/g;
    print;
}

close(N);
#close(M);

Hi DJ,

Ouch! Perl! :)
Thanks, anyway!

Makes sense.

[...]

Hmmm, okay.

I wish I could extract at least part of it, into a bash(1)/sh(1) script.

... and which wouldn't consume the vast amounts of natural resources, both for training and using ...

I've seen maintainers do that; not just random programmers. The problem is that the number of programmers that understand the subtleties language to a point where they can reject a very-subtly-incorrect report isn't very large.

Personally, I've seen only one bug report in a project that I maintain that was actually relevant. And it caught a regression that might have been caught by users in the -rc (since it was disruptive enough), so maybe it wasn't even necessary.

In shadow-utils, FWIW, we haven't seen any AI-helped reports that caught important released vulnerabilities.

It is different, actually. With AI, they can produce something that looks plausibly okay, and is only subtly wrong. If they have no clue of what they're doing, and they don't use AI, it will be apparent, and I'll be able to spot that and help.

Human mistakes and lack of experience are predictable enough, but with an LLM, I must review carefully every little detail.

IME, I've never had a case where an LLM was a net positive, and I've seen cases where it was clearly negative. When I see that with my eyes, my opinion might change. It's not like bicycles, which are clearly positive (maybe the first years they were not so good, but after so many years, they're clearly useful now).

I'll let the rest of the world find that, and when that happens, I might welcome that. For now, I'll stay conservative.

I believe asking an expert is still more effective. If you need any man-related information, you can ask us in this mailing list. You're welcome to ask me; I won't be angry because of stupid questions, I promise.

Yup; I heard that.

:D

The main difference I observe is that deterministic tools like linters and compilers have a more-or-less consistent behavior, with well-known false positives and negatives. If you search in the right forums, or ask an expert, you'll get a good overview of which diagnostics are prone to being bogus. With an LLM, it's a lottery, and they are designed to look as plausible as possible.

Thus, it's much easier to be misled by an LLM than by a compiler false positive diagnostic or some random programmer's bogus bug report.

I certainly trust you using an LLM than some random programmer. But I still have my concerns, even with you.

It's difficult. A patch that has been written with (at some point) corrupted information that looks plausible also looks plausible itself. A patch written by a clueless contributor is more obviously wrong, and thus easier to review.

I don't feel qualified to judge patches after they've been corrupted by an AI at any point in their creation; it's too difficult.

To me, it's comparable to working with Jia Tan, and trying to figure out the exact moment when it'll try to trick me into merging a vulnerability that looks like good code.

A tool designed to produce output that looks plausibly correct even though it might be incorrect is precisely the kind of tool I want to disallow.

Hmmm, it took me some time, but I could understand it. I've translated it to a bash(1) script which I can read better:

	#!/bin/bash

	set -Eeuo pipefail;

	test -v MANPATH    || MANPATH='.:/usr/local/man:/usr/local/share/man';
	test -v MANWIDTH   || MANWIDTH="$(stty size | cut -f2 -d' ')";
	test -v MANROFFOPT || MANROFFOPT='-d AD=l -rCR=1 -P-i';

	width=$(expr "$MANWIDTH" - 2);

	echo $MANPATH \
	| tr : '\n' \
	| xargs -I{} find {} -maxdepth 2 -type f \
	| if test $# -eq 2; then
		grep -E "^(.*/)?$2\.$1[[:alpha:]]*$";
	else
		grep -E "^(.*/)?$1\.[[:digit:]][[:alpha:]]*$";
	fi \
	| head -n1 \
	| xargs groff -mandoc -Tutf8 -rLL="$width"n $MANROFFOPT \
	| sed $'s/\e\[1m/\e\[1;32m/g' \
	| sed $'s/\e\[3m/\e\[3;34m/g' \
	| sed $'s/^\e\[1;32m/\e\[1;31m/g' \
	| sed $'s/\e\[21m/\e\[21;39m/g' \
	| sed $'s/\e\[22m/\e\[22;39m/g' \
	| sed $'s/\e\[23m/\e\[23;39m/g' \
	| less -R;

I guess these days this is unnecessary, since man -l can replace most of it (except for the colors at the end).

Cheers,
Alex

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

Hi DJ,

One per logical change.

The documentation of tunables is one logical change, even if it covers several pages.

The documentation of an include directive in ld.so.conf(5) is a separate logical change.

I think the -t flag of ldconfig(8) could be considered a separate change too.

I suggest using git-format-patch(1). It's very similar to git-show(1), except that it can then be applied on my side with git-am(1).

git-format-patch(1) is best paired with git-send-email(1), but if that's too inconvenient for you, you can paste it as if it were the output of git-show(1). For that, you may want to use the --stdout flag of git-format-patch(1).

I actually like it for its simplicity. Once you learn the few macros, there's not much more that you need to learn.

There's no heading (what do you consider a heading?). It was just a new line after period.

Actually, after a heading (a section heading is .SH) it knows to start a new paragraph:

	.SH DESCRIPTION
	First paragraph.
	No need for '.P' before this.
	.P
	Second paragraph.

But that text was:

@@ -9,6 +9,14 @@ .SH DESCRIPTION
This file contains a list of directories, one per line,
in which to search for libraries.
+The file allows lines to start with the word +.I include
+followed by a path wildcard,
+and will include any files matching that wildcard.

So we need a .P because there's just text there (no headings).

'wildcard' is a technical term referring to a specific pattern (a string containing '?', '*', or '[') in glob(7). I suggest using 'glob(7) pattern' instead. How about this?:

The syntax allows lines to start with the keyword .B include
followed by a pathname
.BR glob (7)
pattern.

And then
Files matching that pattern will be processed

Given they are about different topics, that's fine. Especially, since the page is small. Eyes will be able to find the information they want easily, skipping paragraphs that are not interesting. Otherwise, the brain must parse the entire paragraph, looking for the sentence that is interesting.

Then maybe document this environment vairable in ld.so(8) (which already has an ENVIRONMENT section)?

Oh, sorry, I misread the context. So, you're already outside of the tagged paragraph, and back in the non-indented text. Then, we want:

	.P
	.in +4n
	...
	.in

The reason we use .in instead of .IP is to have a consistent indentation level that can be applied independent of whether we're in a P or IP paragraph (sometimes we want P, and sometimes IP; whatever the context uses).

"type" isn't very specific. The shell first forks, which I guess isn't important, and then that file is exec(3)'d, which (I guess) is what triggers all this?

Hmm.

Ok. Then basename or absolute pathname, I think.

	.SH
	Example configuration file:
	.P
	.in +4n
	.EX
	/lib
	/usr/lib
	/usr/local/lib
	include /etc/ld.so.conf.d/*.conf
	.EE
	.in

	which is a string of the form
	.IB name = value \f[R].\f[]

	$ grep -ro set-user-ID.pro.... 
	man3/getlogin.3:set-user-ID program
	man3/realpath.3:set-user-ID program
	man7/pthreads.7:set-user-ID program
	man7/user_namespaces.7:set-user-ID program
	man7/credentials.7:set-user-ID program
	man7/capabilities.7:set-user-ID program
	man7/keyrings.7:set-user-ID program
	man2/access.2:set-user-ID program
	man2/access.2:set-user-ID program
	man2/execve.2:set-user-ID program

	.P
	.in +4n

	.in

	.SH EXAMPLES
	Example configuration file:
	.P
	.in +4n
	.EX
	...
	.EE

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