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

"G. Branden Robinson" <[email protected]> Wed, 15 Jul 2026 11:54:50 -0500
Newsgroups	org.kernel.vger.linux-man
Message-ID	<20260715165450.iakjkw6qwgcnpzq7@illithid>
Hi DJ,

At 2026-07-15T10:33:58-0400, DJ Delorie wrote:
> Alejandro Colomar <[email protected]> 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

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

> Is ".in +4n" the default for .EX, unless the user changed it?

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.

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

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.

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

What preprocessor?

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

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
signature.asc (application/pgp-signature, 833 B)