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

[Alejandro Colomar <alx@kernel.org>]

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

Hi DJ,

On 2026-07-15T14:19:49-0400, DJ Delorie wrote:
[...]
> > 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/xno6ge8p38.fsf@greed.delorie.com/T/#m9fda91ba28ca257c67d4595f81d38b32c5c9c937
> 
> 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 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.  :)

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

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

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

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.

[...]
> > 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".
> 
> 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.

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

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

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.  (G.Wilford@ee.surrey.ac.uk)

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

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