Everyone loves having instant access to documentation. This is one of
the things Cheat does really well: just type
cheat git and
you've got a git cheat sheet in your terminal. Or in your editor,
whatever. It's cool stuff.
Well, man pages do the same thing. For instance, I've installed
node.js via homebrew which means I can type
man node at any time to
see the docs to the entire node.js standard library. Seriously. Thanks
mxcl and ryah.
If you're using a tool that came with your OS, you can bet there's a man page for it. Unicorn has a great one, so does ack. And if you've installed cmatrix, which I hope you have, it has one too.
It's the way Unix documents things, and it's already really easy for you to access. man pages are worth understanding.
What's a man page?
Man pages (short for manual pages) are the extensive documentation that comes preinstalled with almost all substantial Unix and Unix-like operating systems. The Unix command used to display them is man. Each page is a self-contained document.
You can see one by going to your terminal and typing:
$ man grep
On some systems like Debian, every program is required to come with a man page. I don't know if the same is true for OS X, but all the Mac-specific commands I've used have man pages. For example:
$ man pbcopy
say, and more.
Man pages are a great way to learn about a piece of software. Try
grep or check out
man strftime. Yes, C functions have man pages
What do the sections mean?
man pages are broken into sections:
- General commands
- System calls
- C library functions
- Special files (usually devices, those found in /dev) and drivers
- File formats and conventions
- Games and screensavers
- System administration commands and daemons
This means we can have
markdown(5), two man pages
with the same name that live in different sections. One is a man page
describing a command, typing
markdown in your shell, and one is a
man page describing the Markdown file format. Like what you'd read on
Gruber's Markdown page.
You can specify which you'd like to view like so:
$ man 1 markdown $ man 5 markdown
How do you find man pages?
You can use
apropos on many systems to search for man pages matching
$ apropos ruby macruby(1), ruby(1) - Interpreted object-oriented scripting language cap(1) - Ruby on Rails web applications deployment utility gem(1) - RubyGems program irb(1), erb(1), ri(1), rdoc(1), testrb(1) - Ruby helper programs mongrel_rails(1) - Fast HTTP library and server for Ruby rake(1) - Ruby Make ruby(1) - Interpreted object-oriented scripting language
There are also at least five iPhone apps dedicated to man pages, all of which cost money:
If you're using Ruby, you can discover man pages that RubyGems you've
installed contain by installing
gem-man and using
$ gem install gem-man $ gem man --all These gems have man pages: ronn 0.4.1 unicorn 0.97.0 unicorn 0.96.0 gem-man 0.1.3 mustache 0.6.0
$ gem man 1 mustache
Sweet. There's also Richard Crowley's alias man trick.
How do you write man pages?
man pages are written in a funky macro language as part of a
typesetting system called roff, which dates back to around 1973. That
is, according to
man roff. Anyway, it's nasty - you can look at
mustache.1 for an example. You don't wanna write it by hand.
It's much easier to let a computer generate this markup for us, just like how we let Markdown generate HTML. As far as I know there are two excellent tools you can use to author man pages.
In fact, check this out: I grabbed ParseTree's spartan yet extremely
readable README.txt and ran it through
You can grab AsciiDoc with:
$ brew install asciidoc
or by any of the methods documented on their Installation page.
It, naturally, has a man page: man asciidoc once you've got it installed.
Personally, I like to use Ryan Tomayko's ronn. If you have RubyGems:
$ gem install ronn
Now run it on any README.markdown. I'll try it on Resque's:
$ ronn -b5 README.markdown
It looks even better when passed something in the Markdown derived ronn(5) format:
Here are some I've published:
Perl has Pod - I can
man Apache2::Const and see a different
yet familiar face, presumably a man page generated by
Ruby also has rtfm, a gem for building man pages in Ruby.
Then there's Doxygen, and probably many more.
How do you publish man pages?
For HTML I like to use GitHub Pages. It's pretty easy to write a
Rake task or something that generates a man page's HTML and
publishes it to your
gh-pages branch. I pretty much do it in all my
projects - I'm sure many others do the same.
When you install a Debian or homebrew package, any man pages get installed automatically. This means if you package man pages users will magically get them, and everyone wins.
So let's do that.
Manuals of Interest
Finally, some manuals of interest:
- man fork
- man bash
- man zsh
- man curl
- man httpd
- man 5 crontab
- man netcat
- man gist
- man hub
- man git-rebase
- gem man 7 ronn
- gem man unicorn