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

[DJ Delorie <dj@redhat.com>]

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> The man(7) package doesn't impose a rigid stylesheet on its output.

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

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

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.

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

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

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

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

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

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

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