3 ms·

As well-documented as GNU software is — and it is! remarkably so — I think the project loses even more points for foisting the atrocity that is gnu-info on ever

by rosser 9y ago

As well-documented as GNU software is — and it is! remarkably so — I think the project loses even more points for foisting the atrocity that is gnu-info on everyone. That is some abysmally "You will do it the way I want you to, and like it!" software. When I say `man foo`, do not suggest I look elsewhere, please.

klodolph 9y ago
So, they've written this amazing documentation system which generates info and HTML from the same sources, hosted all the HTML online and made it available as separate downloads, also made it accessible from the terminal using "info", and on top of that they've made a separate, shorter version of the documentation available as a man page and you say that they should lose points for it? Is this actually a problem for you? I'm genuinely curious. "Man" is only really usable when the pages are a reasonable size. Once they get too big, you end up spending most of your time grepping through it or paging forwards and backwards looking for the section you want. But apparently, gnu-info is an "atrocity". Why? Is it somehow morally wrong to ever try to make something better than "man"?
- rosser 9y ago
  An "atrocity" is admittedly hyperbole, but when the man pages are vague, at best, and often just say "use info instead", that reads more "Do it the GNU way, or you're wrong," than, "Weren't we thoughtful to have given you all these alternatives?" Particularly when the former is not an uncommon attitude among FSF projects. I'll totally own that I'm reactive to that, but I really do think it's a little thoughtless, and a violation of the Principle of Least Surprise, to direct people elsewhere. I've been burned entirely too many times, trying to put out a fire, checking the man page to confirm I remember some argument or option correctly, and being told I'm looking in the wrong place. It's not that it's "morally wrong" to do that; it's that it introduces friction in a place where that might be — demonstrably has been, given my experience, which I know I'm not alone in having had — particularly painful. Sometimes, "grepping through the man page" is, in fact, the quickest route to the info you need...
  - klodolph 9y ago
    I mean, sure, it's nice to have the options documented in a man page. But most of the GNU projects have exactly this in addition to the full docs in info pages, multi-page HTML, and single-page HTML available for online or offline browsing. I think historically, there were some bad man pages for GNU projects which just pointed to info, but I haven't seen that happen recently.
    - rosser 9y ago
      Then that's improved markedly since the last time I bothered trying to `man foo` in the terminal for a GNU tool. I just go straight to the web, because at least there I can Ctrl-F properly. I'm not saying "don't even try to improve things", and I think that's a pretty un-generous read of my concern. I'm saying don't break people's expectations. Especially if those expectations might come into play in exigent circumstances, and create friction in a place where the user already has a problem that is far more important to them than whether they're using the output from most flexible documentation tool or not. Like I said, it sounds like that's improved. If so, I'm glad. But I have specifically been burned, and my time that was wasted was also someone else's money. Given that, a bit of, "Hey, guys? Maybe think about how this choice might affect people?" is, IMO, warranted.
      - klodolph 9y ago
        > Given that, a bit of, "Hey, guys? Maybe think about how this choice might affect people?" is, IMO, warranted. That's exactly what I have a problem with... there's a leap between "this sucks" to "therefore they must not care about how this affects other people" that is not justified. If you want something that fits your expectations of how Unix should work, we already have that, it's BSD and it's constructed with a lot of care not to break users' expectations of how Unix works. The GNU project has really never had that as a project goal. The whole "GNU's Not Unix" acronym is not just a stab at copyrights, but it's a pretty good summary of their goal to create something which is not Unix but instead better than Unix. I'm not saying that they're doing it the right way, or that they actually are better, but that's their stated goal. Pretty much every GNU tool has some incompatibility with the equivalent Unix tool, and they don't care, because they're not trying to make a copy of Unix. Back in the day this was a problem because people would write shell scripts which would assume GNU userland. You still see it in a lot of packages which say that you have to use GNU Make, GNU Awk, GNU Sed, GNU Bison, etc. instead of the equivalent Unix program. These pieces of advice have fallen by the wayside since GNU userspace has become the norm, but if you really want the Unix experience instead of the GNU experience, go use BSD.

by rosser 9y ago

klodolph 9y ago

So, they've written this amazing documentation system which generates info and HTML from the same sources, hosted all the HTML online and made it available as separate downloads, also made it accessible from the terminal using "info", and on top of that they've made a separate, shorter version of the documentation available as a man page and you say that they should lose points for it? Is this actually a problem for you? I'm genuinely curious. "Man" is only really usable when the pages are a reasonable size. Once they get too big, you end up spending most of your time grepping through it or paging forwards and backwards looking for the section you want. But apparently, gnu-info is an "atrocity". Why? Is it somehow morally wrong to ever try to make something better than "man"?

rosser 9y ago
An "atrocity" is admittedly hyperbole, but when the man pages are vague, at best, and often just say "use info instead", that reads more "Do it the GNU way, or you're wrong," than, "Weren't we thoughtful to have given you all these alternatives?" Particularly when the former is not an uncommon attitude among FSF projects. I'll totally own that I'm reactive to that, but I really do think it's a little thoughtless, and a violation of the Principle of Least Surprise, to direct people elsewhere. I've been burned entirely too many times, trying to put out a fire, checking the man page to confirm I remember some argument or option correctly, and being told I'm looking in the wrong place. It's not that it's "morally wrong" to do that; it's that it introduces friction in a place where that might be — demonstrably has been, given my experience, which I know I'm not alone in having had — particularly painful. Sometimes, "grepping through the man page" is, in fact, the quickest route to the info you need...
- klodolph 9y ago
  I mean, sure, it's nice to have the options documented in a man page. But most of the GNU projects have exactly this in addition to the full docs in info pages, multi-page HTML, and single-page HTML available for online or offline browsing. I think historically, there were some bad man pages for GNU projects which just pointed to info, but I haven't seen that happen recently.
  - rosser 9y ago
    Then that's improved markedly since the last time I bothered trying to `man foo` in the terminal for a GNU tool. I just go straight to the web, because at least there I can Ctrl-F properly. I'm not saying "don't even try to improve things", and I think that's a pretty un-generous read of my concern. I'm saying don't break people's expectations. Especially if those expectations might come into play in exigent circumstances, and create friction in a place where the user already has a problem that is far more important to them than whether they're using the output from most flexible documentation tool or not. Like I said, it sounds like that's improved. If so, I'm glad. But I have specifically been burned, and my time that was wasted was also someone else's money. Given that, a bit of, "Hey, guys? Maybe think about how this choice might affect people?" is, IMO, warranted.
    - klodolph 9y ago
      > Given that, a bit of, "Hey, guys? Maybe think about how this choice might affect people?" is, IMO, warranted. That's exactly what I have a problem with... there's a leap between "this sucks" to "therefore they must not care about how this affects other people" that is not justified. If you want something that fits your expectations of how Unix should work, we already have that, it's BSD and it's constructed with a lot of care not to break users' expectations of how Unix works. The GNU project has really never had that as a project goal. The whole "GNU's Not Unix" acronym is not just a stab at copyrights, but it's a pretty good summary of their goal to create something which is not Unix but instead better than Unix. I'm not saying that they're doing it the right way, or that they actually are better, but that's their stated goal. Pretty much every GNU tool has some incompatibility with the equivalent Unix tool, and they don't care, because they're not trying to make a copy of Unix. Back in the day this was a problem because people would write shell scripts which would assume GNU userland. You still see it in a lot of packages which say that you have to use GNU Make, GNU Awk, GNU Sed, GNU Bison, etc. instead of the equivalent Unix program. These pieces of advice have fallen by the wayside since GNU userspace has become the norm, but if you really want the Unix experience instead of the GNU experience, go use BSD.