

Man what - mickeyben
http://ozmm.org/posts/man_what.html

======
leif
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.

~~~
telemachos
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
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)

------
danieldon
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.

------
hvs
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?

~~~
travisjeffery
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.

------
noamsml
Upvoted for a nice collection of tools for composing man pages, and the ruby-
man gem, even though some of the information is rather basic.

Also, because I didn't know about the cheatsheet project.

------
andrewcooke
also, "ls" lists files in your current directory.

~~~
scott_s
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.

~~~
andrewcooke
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...

~~~
scott_s
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.

~~~
andrewcooke
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.

------
jamesbritt
"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'?

------
stcredzero
On OS X Snow Leopard:

    
    
        my-macbook:~ user$ man up
        No manual entry for up
        my-macbook:~ user$

------
jff
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.

