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

Alejandro Colomar <[email protected]> writes:
> 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.

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

I don't mean that.

> If you mean source code comments (that is, in the same file),
> I disagree.

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.

> You're welcome to send the patches well before they're merged in glibc.

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.

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

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.

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

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