Submit Hint Search The Forums LinksStatsPollsHeadlinesRSS
14,000 hints and counting!

Yet another way to read beautifully formatted man pages UNIX
Many contributors have come up with ways to read man pages in a more usable format. However, using troff to produce PDFs takes time and I don't really like the output. There are also some excellent man page reading apps out there, but they require launching and browsing a list.

So I came up with a simple shell function to provide exceptionally fast lookups from the Apple Developer site's HTML man pages. That way, you get your nicely-formatted Darwin-specific man pages in a tab in your browser.

The function uses man -w to get the section number and then forms a URL which then gets launched. The web pages are organized by section, and so the URL is not straighforward. I'm new to sed, and my guess is that there are readers that can improve my regex. I've tested this with with a variety of commands, but certainly not exhaustively.

Drop this into your user's .bashrc file. You should also put it into .bash_profile if you maintain them separately -- my .bash_profile has a single line (source ~/.bashrc), so I only have to maintain one.
function wman() {
   url="man -w ${1} | sed 's#.*\(${1}.\)\([[:digit:]]\).*\$#http://developer.apple.com/documentation/Darwin/Reference/ManPages/man\2/\1\2.html#'"
   open `eval $url`
}
Thereafter, you can just type wman and the name of the command you want (e.g., wman rsync). If anyone knows how to automatically scroll the browser down to the horizontal rule, I'd love to know how. There are no named anchor points in the pages, so a # in the URL doesn't work.

[robg adds: Two previous hints on different ways to read man pages: as a PDF in Previewas ASCII, HTML, or PostScript. I tested the wman command in this hint, and it works as described.]
    •    
  • Currently 2.00 / 5
  You rated: 4 / 5 (10 votes cast)
 
[9,059 views]  

Yet another way to read beautifully formatted man pages | 21 comments | Create New Account
Click here to return to the 'Yet another way to read beautifully formatted man pages' hint
The following comments are owned by whoever posted them. This site is not responsible for what they say.
Yet another way to read beautifully formatted man pages
Authored by: Sesquipedalian on May 14, '09 08:13:25AM
This is nice, but it does assume that you are always connected to the net, and it does take a moment or two for the webpage to load.

Personally, I like to use the following. The output is in plain text rather than a pretty webpage, but it is instantaneous, requires no network connection, and gives you all the functions and convenience of TextEdit (or whatever other text editor you choose to use) while working with man pages.

Just add the following lines to .profile (or .bash_profile or whatever applies to your situation) in your home folder.

tman()
{
man "${1}" | col -b | open -f -a "TextEdit"
}


[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: broomdodger on May 14, '09 09:55:28AM

For those of who like to use vim:

vman()
{
man "${1}" | col -bx | view -
}



[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: CarlRJ on May 14, '09 12:15:01PM

Actually, if you're using vim, put this into your .vimrc:

runtime! ftplugin/man.vim

and then, from inside vim, you can type ":Man whatever" (yes, the M must be uppercase) to get nice syntax-colored (you do have syntax on in your .vimrc, right?) man pages in a split window inside vim. Great for referring to documentation while writing scripts.

Oh, and if you haven't checked out a recent version of MacVim, definitely give it a whirl -- it's awesome (best version of the best text editor ever, and it's free).



[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: linux454 on May 15, '09 01:10:50PM

This is what I settled on using MacVim:

function tman {
man "${1}" | col -b | /usr/local/bin/gview - 1>/dev/null 2>&1
}



[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: dgerrity on May 15, '09 08:49:00AM

Thanks for your suggestion -- you're right about the speed, and of course yours works offine. I added that too and now I have both.



[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: linux454 on May 14, '09 08:13:50AM

To support the non-numeric man sections, such as 'n' (for Tcl commands), change your regex to:

.*\(${1}.\)\([[:alnum:]]\).*\$



[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: dgerrity on May 15, '09 08:46:14AM

Thank you -- makes sense.



[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: rflorence on May 14, '09 08:43:40AM
An alternative is to put man.pl into the cgi-bin of a local server and add All 1 2 3 4 5 6 7 8 9 n to your local home page.

[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: etresoft on May 14, '09 09:05:39AM

There are also some excellent man page reading apps out there, but they require launching and browsing a list.

Not necessarily. Using Bwana I can just type "open man:gethostbyname" and instantly see the output in my web browser. It also has searching capabilities. If I'm already in the browser, I can just type "man:gethostbyname" in the address field.

The only problem with Bwana I've found is that if you click on a man link from within Xcode documentation, it opens the man page in Xcode documentation, but also tries to open it in Bwana, but fails. It is annoying but not too big a deal since, while in X code documentation, I typically don't need to lookup man pages.



[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: dcottle on May 14, '09 10:33:55AM

I like bwana too, because I use Firefox and search by typing. Very fast. From there you can print the PDF. It generates an index, which I've bookmarked.



[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: lurch99 on May 14, '09 09:18:14AM

I've always used the following, in this case for "dscl", without the %:

% man -t dscl | pstopdf -i -o ~/Desktop/dscl.pdf



[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: olivermomo on May 14, '09 09:32:09AM

It should be noted that this hint does not display the man pages content stored on your hard drive, therefore it may not display the correct man page for the version of the app that is installed on your computer. For example, if you've installed a more recent version of rsync, this hint will load Apple's rsync man page which describes the behavior of the version of rsync included in Mac OS X, and that may have different options than the one you're running locally.



[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: mat79 on May 14, '09 11:56:31AM
I use bwana and this

function wman() {
   url="man:${1}"
   echo `open $url`
}
it opens the man page in my browser

[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: ptone on May 14, '09 12:18:05PM

as pointed out in the comments on the PDF hint - the key to making this a great option is to cache the PDFs - they then open instantly after a one time conversion.

Will work when your offline - while this one won't

-P



[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: unforeseen:X11 on May 14, '09 12:51:41PM

Looks like I'm the only one still using good old 'man'. :)
Type "/word" to search for "word", press N to go to the next hint and navigate with vim-like controls (F, B, J, K, g, G), that's all I need. :)

---
this is not the sig you`re looking for.



[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: NovaScotian on May 14, '09 02:18:54PM

I use an AppleScript to accomplish this (using pstopdf -> Preview) but in addition to the lookup, for a quicker response next time, I store the results of each unique man page in a folder in ~/Documents. My script then checks that folder first for the term entered and does a man -t lookup of the term only if it's not already on file.



[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: kaih on May 14, '09 04:37:58PM
And if we need any more evidence that there is more than one way to do things, here's what I have in my .bashrc:

function niceman { man -t $@ | open -f -a Preview.app; }

This makes man output PostScript and Preview will convert it to a PDF. On large man pages it may take a few seconds, but on small ones it's nice and quick. All the formatting comes through looking very good.

As an example, I timed "niceman bash" from the time I hit enter to the time I saw the PDF open in Preview - it took around 5 seconds to generate a 64-page PDF.

---
k:.

[ Reply to This | # ]

Yet another way to read beautifully formatted man pages
Authored by: CyberSkull on May 14, '09 06:24:30PM
I like using ManOpen.

[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: dzurn on May 14, '09 09:29:33PM

My thoughts exactly. In the Terminal it's just "manopen zsh" to open the corresponding formatted and linked man page. And you can leave it open while crafting your command-line.

Try it and see, if you don't like it then go back to the ugly Times-Roman uselessly-paginated non-hyperlinked PDF files.

---
Madness takes its toll.
Please have exact change.



[ Reply to This | # ]
Thanks everyone for the great suggestions.
Authored by: dgerrity on May 15, '09 08:51:06AM

The wealth of information on this forum is fantastic.



[ Reply to This | # ]
Yet another way to read beautifully formatted man pages
Authored by: eengstrom on May 20, '09 04:32:20PM
As has been commented, this won't work when not online, but it also wont work for non Apple hosted man pages, such as those from MacPorts or Fink or anything else. Combining the ideas from the various other hints, here is a function I came up with to do it locally for any man page:

    hman() { man -w "$@" \
              && man -w "$@" | xargs zcat -fc | groff -Thtml -man > "/tmp/man-${!#}.html" \
              && open "/tmp/man-${!#}.html"; }
I know I call man -w twice, but that's to avoid any temporary variables - YMMV.

[ Reply to This | # ]