4 ms·

The point about manual pages has always seemed to me to be one of the points where the system fails us. There are a fair number of manual pages that the world

by JdeBP 1y ago

The point about manual pages has always seemed to me to be one of the points where the system fails us. There are a fair number of manual pages that the world at large would benefit from having in the original softwares, that are instead stuck buried in a patches subdirectory in a Debian git repository, and have been for years. This is not to say that Debian is the sole example of this. The FreeBSD/NetBSD packages/ports systems have their share of globally useful stuff that is squirrelled away as a local patch. The point is not that Debian is a problem, but that it too systematizes the idea that (specifically) manual pages for external stuff go primarily into an operating system's own source control, instead of that being the last resort.

guappa 1y ago
That only happens if the project lacks a manual page or if it's really bad.
- JdeBP 1y ago
  "only happens" is a lot more often that you think. In my experience, "only" is quite frequent. A randomly picked case in point: Debian has had a local manual page for the original software's undocumented (in the old Sourceforge version) iptunnel(8) command for 7 years: https://salsa.debian.org/debian/net-tools/-/blob/debian/sid/debian/iptunnel.8 https://salsa.debian.org/debian/net-tools/-/blob/debian/sid/... Independently, the original came up with its own, quite different, manual page 3 years later: https://github.com/ecki/net-tools/blob/master/man/en_US/iptunnel.8 https://github.com/ecki/net-tools/blob/master/man/en_US/iptu... Then Debian imported that! https://salsa.debian.org/debian/net-tools/-/blob/debian/sid/man/en_US/iptunnel.8 https://salsa.debian.org/debian/net-tools/-/blob/debian/sid/... This sort of thing isn't a rare occurrence.
  - guappa 1y ago
    Wow 1 instance. Ok. World ending.
pabs3 1y ago
Usually the Debian manual page author or package maintainer will send that upstream. Same goes for patches. Sometimes upstream doesn't want manual pages, or wants it in a different format, and the Debian person doesn't have time to rewrite it.
- ckastner 1y ago
  This. And often it's not an unhelpful upstream, just an upstream that sees little use for man pages in their releases, and doesn't want to spend time maintaining documentation in parallel to what their README.md or --help provides (with which the man page must be kept in sync).
- JdeBP 1y ago
  There's a belief that this is usual. But having watched the process for a couple of decades, it seems to me that that is just a belief, and actual practice doesn't work that way. A lot of times this stuff just gets stuck and never sent along. I also think that the idea that original authors must not accept manual pages is a way of explaining how the belief does not match reality, without accepting that it is the belief itself that is wrong. Certainly, the number of times that things work out like the net-tools example elsethread, where clearly the original authors do want manual pages, because they eventually wrote some, and end up duplicating Debian's (and FreeBSD's/NetBSD's) efforts, is evidence that contradicts the belief that there's some widespread no-manual-pages culture amongst developers.
  - capitol_ 1y ago
    It's also easy for people to have the opinion the those who do the unpaid work of packaging software should do even more work for free. I have sent about 50 or so patches upstream for the 300 packages I maintain and while it reduces the amount of work long-term it's also surprisingly amount of work. Typically the Debian patches are licensed under the same license as the original project. So there is nothing stopping anyone who feels that more patches should be sent upstream to send them. Typically the Debian maintai
    - 1y ago
deleted 1y ago
[deleted]
jmmv 1y ago
I spent years packaging software (mostly Gnome 2.x) for NetBSD. I almost-always tried to upstream the local patches that were needed either for build fixes or improvements (like flexibility to adapt to non-Linux file system hierarchies or using different APIs). It was exhausting though, and an uphill battle. Most patches were ignored for months or years, with common “is this still necessary?” or “please update the patch; it doesn’t apply anymore” responses. And it was generally a lot of effort. So patches staying in their distros is… “normal”.
arp242 1y ago
Another issue is that these manpages can become outdated (and/or are downright wrong). Overall I feel it's one of those Debian policies stuck in 1995. There are other reasonable ways to get documentation these days, and while manpages can be useful for some types of programs, they're less useful for others.

by JdeBP 1y ago

guappa 1y ago

That only happens if the project lacks a manual page or if it's really bad.

JdeBP 1y ago
"only happens" is a lot more often that you think. In my experience, "only" is quite frequent. A randomly picked case in point: Debian has had a local manual page for the original software's undocumented (in the old Sourceforge version) iptunnel(8) command for 7 years: https://salsa.debian.org/debian/net-tools/-/blob/debian/sid/debian/iptunnel.8 https://salsa.debian.org/debian/net-tools/-/blob/debian/sid/... Independently, the original came up with its own, quite different, manual page 3 years later: https://github.com/ecki/net-tools/blob/master/man/en_US/iptunnel.8 https://github.com/ecki/net-tools/blob/master/man/en_US/iptu... Then Debian imported that! https://salsa.debian.org/debian/net-tools/-/blob/debian/sid/man/en_US/iptunnel.8 https://salsa.debian.org/debian/net-tools/-/blob/debian/sid/... This sort of thing isn't a rare occurrence.
- guappa 1y ago
  Wow 1 instance. Ok. World ending.

pabs3 1y ago

Usually the Debian manual page author or package maintainer will send that upstream. Same goes for patches. Sometimes upstream doesn't want manual pages, or wants it in a different format, and the Debian person doesn't have time to rewrite it.

ckastner 1y ago
This. And often it's not an unhelpful upstream, just an upstream that sees little use for man pages in their releases, and doesn't want to spend time maintaining documentation in parallel to what their README.md or --help provides (with which the man page must be kept in sync).
JdeBP 1y ago
There's a belief that this is usual. But having watched the process for a couple of decades, it seems to me that that is just a belief, and actual practice doesn't work that way. A lot of times this stuff just gets stuck and never sent along. I also think that the idea that original authors must not accept manual pages is a way of explaining how the belief does not match reality, without accepting that it is the belief itself that is wrong. Certainly, the number of times that things work out like the net-tools example elsethread, where clearly the original authors do want manual pages, because they eventually wrote some, and end up duplicating Debian's (and FreeBSD's/NetBSD's) efforts, is evidence that contradicts the belief that there's some widespread no-manual-pages culture amongst developers.
- capitol_ 1y ago
  It's also easy for people to have the opinion the those who do the unpaid work of packaging software should do even more work for free. I have sent about 50 or so patches upstream for the 300 packages I maintain and while it reduces the amount of work long-term it's also surprisingly amount of work. Typically the Debian patches are licensed under the same license as the original project. So there is nothing stopping anyone who feels that more patches should be sent upstream to send them. Typically the Debian maintai
  - 1y ago

deleted 1y ago

[deleted]

jmmv 1y ago

I spent years packaging software (mostly Gnome 2.x) for NetBSD. I almost-always tried to upstream the local patches that were needed either for build fixes or improvements (like flexibility to adapt to non-Linux file system hierarchies or using different APIs). It was exhausting though, and an uphill battle. Most patches were ignored for months or years, with common “is this still necessary?” or “please update the patch; it doesn’t apply anymore” responses. And it was generally a lot of effort. So patches staying in their distros is… “normal”.

arp242 1y ago

Another issue is that these manpages can become outdated (and/or are downright wrong). Overall I feel it's one of those Debian policies stuck in 1995. There are other reasonable ways to get documentation these days, and while manpages can be useful for some types of programs, they're less useful for others.