For context, he just created the gem-man gem 2 days ago. Presumably he's just collecting a bunch of basic information in one place as part of the process, including new and specific information on tools for making dealing with man pages in gems. I don't see what the problem is, and feigning shock over someone talking about man pages doesn't make you look cool.
Overall, I think you're right about Chris's point, but I'm not sure about your comparison of how many gems versus how many manpages.
Many gems are libraries rather than binaries/applications, and as such they don't have user-friendly man pages, but they do have documentation in the form of rdoc/yard/what-have-you. On my system, only gem-man and ronn have manpages, but many other gems have documentation via ri - it's just documentation aimed at other programmers rather than end users. For a library, that makes sense to me.
Having said that, it would be nice if Ruby gem authors got into the habit of using ronn and gem-man in the way that Perl CPAN authors use POD.
Also, and this is just nitpicky, but your second command shouldn't need awk, sort or uniq:
So yes, some of these gems don't need man-pages. I wasn't hoping for 100% man-page coverage (maybe an interesting tool to write, now that I think of it...), but better than one apart from the gem-man quasi-meta-manpage would be a start.
In particular, I'm thinking of things like rails, rspec, heroku, and the like, which, while primarily libraries, have cli components that badly need man pages. I can't tell you how many babies I've punched as a result of typing "man rails" or "man spec". It might be just me, but if it can be the first token in a shell command, I expect it to have a manpage, and it is almost (physically) shocking when that is not true.
(I do need that awk | sort | uniq, because I have multiple versions of unicorn that all show up with that command)
If that's the point, it would have been made far better by posting the above sentence, rather than delivering a tutorial for retarded six year olds on how to use the 'man' command.
Holy crap. Am I just so old that I don't realize that the younger generation has never been exposed to basic unix commands, or is this article as ridiculous as it seems?
I think Chris is mainly writing for the Ruby community; in a talk he gave at RubyConf '09 (http://tr.im/Rbui) he talked about things that Python did better than they and one big thing he said was how adamant the Python people are on documentation.
I think it's probably 20% newest programmers are getting less and less interested in the command-line, 20% article is ridiculous and 60% dude was bored wanted to write an easy and thorough article on a programming topic.
That's unfair. I was thinking the same thing when I first started reading, but he provides pointers to excellent resources for producing manpages. I've written manpages before, and I hadn't heard of asciidoc or ronn.
It's easy to posture and and use snark to deride someone for saying something you already know. But I think gentle reminders that our systems are discoverable is a good one. I'm currently TAing a Computer Systems course, and that's a key point I want our students to realize.
oh come on. first i wasn't deriding the original post - if i was "deriding" anything, it was whoever decided it was worth posting here (and those that upvoted it). second, if a rather gentle observation like that is enough to get you offended, you're too sensitive. or you get your rocks off "defending" people that don't need it, or whatever...
Or I like that HN encourages good discussion. Sarcastic "I already knew that" posts are not good discussion. And I did upvote it, for that reminder and for the pointers to the programs that aid in writing manpages.
one good thing about HN is that it's selective. there's always some small nugget of information in a post, if you look hard enough. that shouldn't be sufficient for an up-vote.
"also, "ls" lists files in your current directory."
It's fantastic that you're very comfortable with Unix-based operating systems! Unfortunately, there are lots of people that aren't. There was a time when you weren't.
This is probably the most straightforward explanation of man that I've ever seen, and I have bookmarked it in order to pass it on when I encounter people who would benefit. I don't know about you, but I really enjoy helping people out who are struggling to learn something new.
I hope someday we can get past Unix "RTFM" culture.
I think you missed the point of the article. Chris himself invented a man alternative, called cheat, and he seems to have had a revelation that maybe the man standard is a good one.
Ruby itself has ri and rdoc as man alternatives.
I think the point was that man is a widely accepted "unix way" of doing documentation. Just as Unicorn uses unix sockets to great effect, maybe we should focus on writing good manpages instead of reinventing documentation systems over and over again.
That doesn't mean cheat, ri, rdoc aren't better in various ways, just that publishing documentation via the man standard is a nice way to maintain standardized docs.
"For instance, I've installed node.js via homebrew which means I can type man node"
Hmm. If I release a project, node.hs, can I also name my man page 'node'? What happens if there is a collision?
Are there rules of etiquette when deciding what to call you man pages entry? I.e., what it not have been better for node.js to have it's entry be 'nodejs' or 'node.js'?
Awww, troff too hard? It's easier than LaTeX, and honestly if you can't open up a man page and replace its content with your own (since they all follow pretty much the same format), you shouldn't even be writing code.
