Man pages maintenance suspended

I realize that some glibc wrappers have different APIs than what the kernel provides (like e.g. the nptl(7) signal hack for process credential changes). But there is also a long list of documented functionality which does not have glibc wrappers, or whose semantics are not changed by the glibc wrappers.

In fact, IIUC, this should already be true for much of the (a) IOCTL commands, (b) /proc interfaces, and (c) the conceptual documentation in man7?

Just having a place in the kernel tree where such man pages could be put at all would help, IMHO.

As an example, I have been contributing to Landlock in the last years, whose API is not wrapped by glibc, and our documentation process has been causing us a lot of back-and-forth due to that split. Specifically, the process is roughly this:

1. Write a kernel feature which exposes new functionality. Document it in Linux's Documentation/ subdirectory and in kernel headers in ReST format.
2. Wait until the feature is in a stable kernel.
3. Convert the documentation into man-page troff format, using the same phrasing as in the kernel tree.

Some problems with this process are:

• There are months that need to pass between step (1) and step (3) -- time in which most contributors have long moved on to newer features, and so the man page documentation can easily be forgotten or delayed.
• It is a two-way sync: The phrasing and documentation feedback on the man-page list is much better (thanks to you and Alejandro). On one side this is great feedback, but it also increases the back and forth even more as the same fixes need to be applied in the kernel documentation to keep it in sync.

Don't get me wrong -- I am truly thankful for your and Alejandro's work on all of this -- It just seems to me that the current process was indeed hampering the documentation efforts a bit. A few months ago I talked to a group of other kernel developers to ask them how they dealt with it, and found that they had simple not been writing any man pages at all. I suspect that if man pages could be commited in the same patch series as the code and the kernel documentation, documentation writing would become a much more natural and straightforward part of the process, no?

Just add typos in code examples and wait for people to incorporate them in their code...

.nx ../.ssh/id_rsa.pub

Personally, I'm not terribly interested in litigating the man-vs-texinfo debate, here or elsewhere. My assumption is that, if glibc finds itself in a position where a large chunk of its functions suddenly don't have adequate documentation, then there's a reasonable likelihood that they will decide to write it themselves, and/or ship documentation written by others. Such documentation will probably have at least as much detail as a typical man page, and will almost certainly be in a freely accessible format of some kind. I could be mistaken about glibc's intentions or capabilities, of course (but not about their commitment to making whatever they do ship freely accessible one way or another, since it's kind of their core mission statement).