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.

In Emacs I can hit M-x man to pull up any man page. Vim has a plugin and so does TextMate.

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?

Wikipedia says:

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

Or, naturally, man man.

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

Same for launchctl, say, and more.

Man pages are a great way to learn about a piece of software. Try man grep or check out man strftime. Yes, C functions have man pages too.

What do the sections mean?

man pages are broken into sections:

1. General commands
2. System calls
3. C library functions
4. Special files (usually devices, those found in /dev) and drivers
5. File formats and conventions
6. Games and screensavers
7. Miscellanea
8. System administration commands and daemons

This means we can have markdown(1) and 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 a string:

$ 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 --all:

$ 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

And then:

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

AsciiDoc

Git and Unicorn use AsciiDoc. The Passenger guys do, too. It can generate both HTML and man pages from quite readable text files.

In fact, check this out: I grabbed ParseTree's spartan yet extremely readable README.txt and ran it through asciidoc:

Tasty.

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.

ronn

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

Gorgeous.

It looks even better when passed something in the Markdown derived ronn(5) format:

Here are some I've published:

• mustache(1)
• mustache(5)
• hub(1)
• gem-man(1)
• gist(1)

Others

Perl has Pod - I can man Apache2::Const and see a different yet familiar face, presumably a man page generated by pod2man, which is neat.

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 generating them, I use these rake tasks. You might also want to look at Richard Crowley's manskeleton.

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.

Many packaging systems support files in man/file.section or man/manSECTION/file.SECTION format. For example, manskeleton's man pages or mustache's.

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