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

[Alejandro Colomar <alx@kernel.org>]

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

Hi DJ,

On 2026-07-15T10:33:58-0400, DJ Delorie wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> >> 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'
> 
> Ok, now you have a new rule that's even easier to not know about :-P

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

> > Also, the manual pages should be readable in the form they exist in the
> > repository
> 
> Not a problem here, a different indentation doesn't affect readability.

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.

> > (and match as much as possible how it will render when
> > installed).
> 
> 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 ;-)

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.

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

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

> > That makes it easy to see if a change works, by running man(1) on the
> > source code.
> 
> Yup, I have my own lman script that acts like man(1) but takes a
> filename instead of a man page reference,

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)

> 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?

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?

> >> and two .EX's that do not have a closing .EE.
> >> Turns out Gemini is good at perl.
> >
> > Please don't use LLMs for contributing to this project.
> 
> 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.

Thanks!

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

(I'll paste this below to reply.)

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

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.

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

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

> > The file "CONTRIBUTING.d/ai" contains our guidelines for their use,
> > which essentially says it's not allowed.
> 
> glibc is the same way, I'm used to that.

Nice to hear that glibc doesn't allow AI!

> 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'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:]
> 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.

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 refuse to follow any policy that tells me what my morals should be in
> the privacy of my own home.

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>

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