On Viewing man Pages

When you frequently use Terminal, you will use man pages. They contain tons of useful information on most of the tools and commands you use on the shell.

Note: update for macOS Ventura

However, the man command’s user interface was designed for terminal output decades ago and does not really integrate well with the modern macOS UI. When you run the man command the output will take over your current Terminal window and scrolling through long man pages can be tedious.

X-man

However, on macOS you do not have to man like it’s 1989.

First solution is to use

$ open x-man-page://ls

instead of man. This will open the man page in a new yellow Terminal window, so you can still see what you are actually doing, while reading the man page. If the yellow is just too annoying for you, you can change the look of the window by changing the ‘Man Page’ window profile in the Terminal Preferences. Since this window shows the entire man page, you can scroll and even use ‘Find’ (Command-F) in this window.

Since typing this open command is a bit awkward, you can add a function to your bash profile or bashrc file:

function xmanpage() { open x-man-page://$@ ; }

Note: You could use xman here. However, that will conflict with another command when you have X11/XQuartz installed.

You can also put ‘x-man-page:’ URLs in other applications, such as emails or chat applications. However, not all applications will recognize URLs starting with x-man-page: as URLs, so your results may be mixed. It does work in Slack, even though Slack is skeptic of the links:

Taken from Context

In Terminal, you can open a man page from the context menu. Simply do a secondary (ctrl/right/two-finger) click on a word in a Terminal window and choose ‘Open man Page’ from the context menu. This will open the man page in a separate window, like opening x-man-page URLs.

man Page with a (Pre)view

Back in the early days of computing you could (or had to) convert man pages into postscript output, so they would look nicer when printing. These options are still present and we can (ab)use them to show a man page in Preview. (Please don’t waste paper printing man pages.) The command for this is:

$ man -t ls | open -f -a "Preview"

The -t options pipes the man page into another tool (groff) to reformat it into pdf which we then pipe into open and send to the Preview application. (More on the open command.) If you use this more frequently, you want to create a function for this in your bash profile or .bashrc:

function preman() { man -t "$@" | open -f -a "Preview" ;}

Text Editors

You can also send a man page to a tex editor. Before you pipe the output into a text editor, you have to clean it up a bit:

$ MANWIDTH=80 MANPAGER='col -bx' man $@ | open -f

This will open in TextEdit. If your favored text editor can receive data from stdin, then replace the open -f with its command. For BBEdit, this will work great:

$ MANWIDTH=80 MANPAGER='col -bx' man $@ | bbedit --clean --view-top -t "man $@"

And again, if want to use this method frequently, create a bash function for it.

ManOpen

The ManOpen application has been around for a long, long time, but amazingly, it still works on macOS Sierra. It will also display man pages in a separate window. The main advantage MacOpen has over the other solutions here is that it will automatically detect other commands and highlight them as hyperlinks to their man pages. There is also a command line tool, confusingly called openman to open the app directly from the Terminal.

Automation

You can also create an Automator Service for this. Then you can open man pages from (nearly) any application with a keystroke or from the context menu. I described this in an older post on man pages.