4 ms·

I think the point is "hey people let's stop releasing software without decent user documentation because that's lazy and lame". And I agree wholeheartedly. ED

by leif 17y ago

I think the point is "hey people let's stop releasing software without decent user documentation because that's lazy and lame". And I agree wholeheartedly. EDIT: For example: % gem list | wc -l 89 % gem man --all | tail -n +3 | awk '{ print $1 }' | sort | uniq | wc -l 2 ...one of those two is gem-man itself. The other is unicorn.

tjic 17y ago
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.
telemachos 17y ago
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: gem man --all | tail -n +3 | wc -l
- leif 17y ago
  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)

by leif 17y ago

tjic 17y ago

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.

telemachos 17y ago

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: gem man --all | tail -n +3 | wc -l

leif 17y ago
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)