On man Pages

Note: update for macOS Ventura

So you’re writing this email explaining to a customer or colleague on how to do some really cool thing (say hide a file in the Finder) in Terminal. The command for that is chflags, but of course you can’t remember the exact syntax. So you open Terminal and write man chflags and find the correct options.1

However reading longer man pages (try ssh or bash) in the Terminal can be kind of painful. I’m sure some of you have encountered this command before:

man -t chflags | open -f -a "Preview"

which uses the -t flag to pass the output to groff and generate a postscript file which we then pipe into the Preview app, using open‘s -f option to pipe the stdin into a file to open in a GUI app. Preview will then convert the postscript to PDF and display the result.

I think this started to work in Tiger and you should immediately go and add this command to your shell’s profile.2 Which is nice but you still have to make the roundtrip to the Terminal.3

Enter Snow Leopard Automator Services. Open Automator. Create a new service. Leave the settings to work on ‘text’ in ‘any application’. Search for the ‘Run Shell Script’ action and double click to add to the workflow. Leave the Shell at ‘/bin/bash’ but set the ‘Pass Input’ option to ‘as arguments.’

Replace the default code with

man -t "$1" | open -f -a /Applications/Preview.app
Screenshot of the workflow in Automator

Save the Service and give it a nice name, such as “Open Man Page.”

Then in any application4 you can ctrl/right/double-finger click on a word and “Open Man Page” will be an option in the menu.5 You can even go to System Preferences -> Keyboard -> and add a keyboard shortcut to the command.6 If any other command in the man page strikes your curiosity, just ctrl/right/double-finger click the word in Preview and select “Open Man Page” again.

Another rarely known but quite useful trick is that you can create hyperlinks to man pages with the x-man-page://command URL.7 This will open the man page in man in a new Terminal window. This is especially useful in IM sessions.


  1. chflags [no]hidden /path/to/file
  2. for me the relevant line looks like: function preman() { man -t "$@" | open -f -a "Preview" ;}
  3. though you could save the resulting PDF and attach it to the email, especially if you have a customer who can’t find his or her way around the command line.
  4. well… most…
  5. it may be under a under an extra level “Services” Menu. Some applications do not show Services in the context menu, but all will show the “Services” Menu under the Application Menu
  6. I usually don’t bother since I immediately forget any new keystrokes I assign. Your memory may work better.
  7. I once had somebody freak out on me because I made him open Terminal on his Mac with this…