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

Read Unix manpages in Safari via the shell and Bwana Apps
I never got quite around to reading Unix manual pages anywhere else than in the shell with the built-in man command. The freeware manpage renderer Bwana finally made me reconsider, as it, IMHO, renders man pages really beautifully in HTML. All that's missing from Bwana is the possibility to invoke it from the shell, as for example to read the manpage of man:
 $ bwana man
Would then open the manpage in a new tab in Safari. So I slapped together a script that opens Safari if it's not yet open, activates it, checks for an existing window and opens one (if there is none) or a tab (if there is a window). Then it constructs a URL to the manpage of the form man:/usr/share/man/man1/man and passes it to the shell command open, which in turn passes the URL to Safari, which invokes the handler for the man: protocol, which happens to be Bwana ... whew! This just works for me with Safari and is in no way optimised. To make it work with other browsers, the AppleScript portion of the shell script has to be adapted. Also, I'm neither really proficient in shell nor AppleScripting, so unexpected things might happen with this script. Access for assistive devices has to be enabled in the Universal Access preference pane; otherwise the last AppleScript line won't work. Save the script somewhere in your path and call it something meaningful (e.g. bwana as in the example above) and make it executable (chmod 755 bwana).
#!/bin/sh

/usr/bin/osascript -e 'tell application "Safari" to activate'
#
# The following three lines must be one long line with a 
# space replacing each line break!
/usr/bin/osascript -e 'tell application "System Events" to tell
 application process "Safari" to click menu item "New Tab" of
 menu "File" of menu bar item "File" of menu bar 1'
#
/usr/bin/open 'man:'$(/usr/bin/man -w $1 | /usr/bin/sed 's/\/.*\///')
[robg adds: This worked as described for me...]

Update: See Kirk's (kirkmc) comment below for a much easier way to make this work!
    •    
  • Currently 2.50 / 5
  You rated: 3 / 5 (4 votes cast)
 
[18,154 views]  

Read Unix manpages in Safari via the shell and Bwana | 21 comments | Create New Account
Click here to return to the 'Read Unix manpages in Safari via the shell and Bwana' hint
The following comments are owned by whoever posted them. This site is not responsible for what they say.
Read Unix manpages in Safari via the shell and Bwana
Authored by: Gobo on Dec 09, '04 10:41:23AM

This also works when using Firefox. However, it does display an error (even though it works correctly):

74:152: execution error: System Events got an error: NSReceiverEvaluationScriptError: 4 (1)



[ Reply to This | # ]
Read Unix manpages in Safari via the shell and Bwana
Authored by: jeremyp on Dec 09, '04 10:54:25AM

I just have a bookmark to the following URL in Safari

http://developer.apple.com/documentation/Darwin/Reference/ManPages/index.html

Only works if you're on-line of course.



[ Reply to This | # ]
Read Unix manpages in Safari via the shell and Bwana
Authored by: kirkmc on Dec 09, '04 11:52:24AM

Um, why not do it the easy way:

open man:man

Then just swtich to your browser.

---
Read my blog: Kirkville -- http://www.mcelhearn.com
Musings, Opinion and Miscellanea, on Macs, iPods and more



[ Reply to This | # ]
Read Unix manpages in Safari via the shell and Bwana
Authored by: gospodin_david on Dec 09, '04 12:39:18PM

There is one problem with this approach. If Safari is open, but there are no Safari windows open, "open man:" doesn't do anything.



[ Reply to This | # ]
Read Unix manpages in Safari via the shell and Bwana
Authored by: osxpounder on Dec 09, '04 03:23:53PM

It doesn't do anything for me even with Safari running and at least one Safari window open -- the one I'm using now to write to you.

Was I supposed to type "open man:man" in the Safari address bar instead of in Terminal? Neither approach did anything for me.

---
--
osxpounder



[ Reply to This | # ]
Read Unix manpages in Safari via the shell and Bwana
Authored by: MattHaffner on Dec 09, '04 03:49:17PM

Did you download Bwana? You have to download it first before anything will happen. It *is* the handler for 'man:' URLs. Then you can type "man:man" in Safari or "open man:man" in the terminal (or use the shell script above...).

mh



[ Reply to This | # ]
Read Unix manpages in Safari via the shell and Bwana
Authored by: osxpounder on Dec 10, '04 01:25:33PM

Ah, OK. I misunderstood. I thought the advice meant that Bwana wasn't needed. Thanks for clearing that up for me!

---
--
osxpounder



[ Reply to This | # ]
Read Unix manpages in Safari via the shell and Bwana
Authored by: aaronrp on Dec 09, '04 03:39:56PM

That's one problem. Also, at least on my system, it replaces the currently open web page with the manpage -- which, usually, is not what I want, since I may want to leave the currently open web page open. The script opens a new tab for it.



[ Reply to This | # ]
Even easier...
Authored by: Viridian on Dec 09, '04 08:14:24PM
Thanks for the great hint kirkmc, but here's something even easier than typing 'open man:[command]' each time. I used your hint and created a shell alias (tcsh; I'm too lazy to get around to learning about bash):

alias mn 'open man:\!:1'

So I just type 'mn [command]' now. Of course, you can change 'mn' to any name that suits you. The only problem is that the alias won't accept nothing as a command (for calling up the index with 'man:'), so I created another alias for that:

alias mndx 'open man:'

Bwana's great by the way, and I tried the script in the hint, but it didn't open a new tab in Safari, it just loaded in the front-most window. Otherwise it worked, but returned the error message,

'syntax error: Expected expression but found end of line. (-2741)'

Anyone have an idea as to what's happening here?



[ Reply to This | # ]
Read Unix manpages in Safari via the shell and Bwana
Authored by: covisp on Mar 19, '06 07:15:47AM

While typing "open man:man" at the command line does work, the problem is that it loads that into the current browser window. This is never what I want.

However, the script posted has a rather long delay between opening a new tab and loading the man page into the new tab.

It's too bad that Applescript cannot tell Safari to open a URL in a new tab, or even a new window, without using the GUI Scripting, which is so very slow.

I think something might be possible with the do javascript command, however.

do JavaScript "window.open('man:man', 'bwama')" in document 1

works, but despite naming the window, it still loads the url into whatever window/tab is frontmost when it finally gets around to actually loading the URL. On my machine that's a delay of three or four seconds, easily long enough to have switched windows. In short, this is no better than the previous solution. I hope that this might lead someone to a solution that does work.



[ Reply to This | # ]
tkinfo
Authored by: the_shrubber on Dec 09, '04 12:09:42PM
See also tkinfo and TclAqua. TkInfo is a graphical browser for info. It is written in Tcl/Tk, so you can use TclAqua to make it run natively. Note, however, that I had to change the top bit of the tkinfo script to exec /usr/bin/wish "$0" "$@"

[ Reply to This | # ]
For a GUI man page viewer, try ManOpen
Authored by: ClassicUser on Dec 09, '04 09:58:30PM
Bwana does seem nice, and using your web browser is slick, but if the end result desired is a GUI approach to viewing man pages, why go any farther than ManOpen? (also, see the 5-star-rated VersionTracker entry).

ManOpen has a great UI, comes with a command-line tool ('openman'), can open entries directly from the app, can perform Apropos searches, etc. etc. etc.

Very powerful, and very Mac-like. An absolutely indispensible utility, IMHO.



[ Reply to This | # ]

For a GUI man page viewer, try ManOpen
Authored by: farranco on Dec 10, '04 06:38:33AM
ManOpen is okay, but I like Bwana output better and using it from Safari without having to open another application I what I wanted, also to be able to click on other man pages as links and websites in the OTHER section is convenient. Not to mention that my brother sends me request for information or tips and he embeds man: urls in the emails, all I have to do is click them.

All that said what I need to add now is an option for always opening new tabs in Safari. The problem is the finder passes the URL to Bwana so I can never tell who is calling Bwana, If I were able to tell I could open a new window if it was not the browser.

Click here for your man index

[ Reply to This | # ]

I miss support for alternate man paths
Authored by: guybrush on Dec 10, '04 06:30:09AM

I cant seem to get man pages for fink installed apps..



[ Reply to This | # ]
Perl script
Authored by: hayne on Dec 10, '04 06:33:04AM
Here (below) is a Perl script that will pass the appropriate 'man:' URL to Safari, opening either a new window or a new tab according to your choice. (Edit the last line of the script to choose which way you want it to work.) Note that opening a new tab (as in the original script suggested in the article) requires that "Assistive Devices" be enabled in the Universal Access preferences. The script checks for this and shows you the Apple web page about enabling this if it is currently disabled.

As usual, you need to save this script into a file, make that file executable (with 'chmod +x') and make sure that file is in a folder that is on your execution PATH.

Sample use (in a Terminal window), assuming you saved it in a file called "mann":

mann ps
mann

The first would show the man page for 'ps'.
The second would show the index page of all available man pages.


#!/usr/bin/perl -w
use strict;

#---------------------------------------------------------------
# This Perl script is for use with "Bwana" (or other 'man:' protocol handler)
# as described on this MacOSXHints page:
# http://www.macosxhints.com/article.php?story=200412080923108
#
# Invoke this script with one command-line argument specifying the name
# of a Unix man page topic and it will display that man page in Safari.
# If you invoke it without any command-line argument, it will show an
# index page of all available man pages.
# (If you invoke it with the special command-line argument "refresh_index",
#  it will pass this on to Bwana with the effect of ignoring any cached
#  index page or MANPATH.) 
#
# Note that there are two different Perl functions available:
# - newSafariWindowWithUrl
# - newSafariTabWithUrl
# The latter requires that "Assistive Devices" be enabled in the
# Universal Access System Preferences.
# The default is to use 'newSafariWindowWithUrl' so if you prefer
# having a new tab instead of a new window, change the last line
# of the script to use 'newSafariTabWithUrl' instead.
#
# Cameron Hayne (macdev@hayne.net) December 2004
#---------------------------------------------------------------

# -- FUNCTIONS --

# runAppleScript: Runs the supplied AppleScript
#                 The argument is the text of the AppleScript.
sub runAppleScript($)
{
    my ($ascript) = @_;

    my $result = `/usr/bin/osascript<<"    EOT"
    $ascript
    EOT
    `;
    chomp($result);
    return $result;
}

# newSafariWindowWithUrl: Opens a new Safari window with the given URL
sub newSafariWindowWithUrl($)
{
    my ($url) = @_;

    runAppleScript(qq(

    tell application "Safari"
	activate
	make new document at end of documents
	set URL of document 1 to "$url"
    end tell

    ));
}

# newSafariTabWithUrl: Opens a new Safari tab with the given URL
sub newSafariTabWithUrl($)
{
    my ($url) = @_;

    runAppleScript(qq(

    -- bring Safari to the front
    tell application "Safari"
	activate
    end

    -- check that GUI Scripting has been enabled
    tell application "System Events"
	if UI elements enabled is false then
	    tell application "Safari"
		make new document at end of documents
		set URL of document 1 to "http://www.apple.com/applescript/uiscripting/01.html"
	    end tell
	    set message to "You need to enable Assistive Devices as explained on this web page"
	    display dialog message buttons {"OK"}
	    return
	end if
    end tell

    -- create the new tab
    tell application "System Events"
	tell process "Safari"
	    click menu item "New Tab" of menu "File" of menu bar 1
	end tell
    end tell

    -- set the new tab to show the given URL
    tell application "Safari"
	set URL of document 1 to "$url"
    end tell

    ));
}


# -- MAIN --

my $topic = "";
if (@ARGV >= 1)
{
    $topic = $ARGV[0];
}

# Uncomment whichever of the two functions you want to use:
#newSafariTabWithUrl("man:$topic");
newSafariWindowWithUrl("man:$topic");



[ Reply to This | # ]
Perl script
Authored by: farranco on Dec 10, '04 08:06:28AM

I added the ability to modify the Bwana AppleScripts internally in the new version and made this script available with the new Bwana. All you have to do is change the script in the file scripts.strings in Bwana's resource folder.



[ Reply to This | # ]
Read Unix manpages in Safari via the shell and Bwana
Authored by: rohanl on Dec 10, '04 07:05:28AM
I personally just use man in the shell, but you don't need any 3rd party tools to produce html man pages. All you need to use is the '-t' option and tell groff to output html. eg: Here's a shell script that will do that and open the file up in Safari

#!/bin/sh

GROFF_TYPESETTER=html
export GROFF_TYPESETTER

/usr/bin/man -t $* >/tmp/hman.html

/usr/bin/open /tmp/hman.html
You don't get index and cross referencing etc, but email addresses and links in the man page are clickable.

Also IMHO the output looks better than what I've seen in the screenshot from Bwana. Instead of just looking like the standard shell output rendered in html, it is properly typeset with proportional fonts, bold, italics and large headings.

Also if you ever want to print man pages, you can use the '-t' option (don't set GROFF_TYPESETTER) to output postScript output.

[ Reply to This | # ]

Read Unix manpages in Safari via the shell and Bwana
Authored by: covisp on Mar 19, '06 07:23:16AM

This does not seem to work on my machine. I get Postscript output in the hman.html file.



[ Reply to This | # ]
PDF Unix manpages with Whatis Command Finder
Authored by: pieromac on Dec 10, '04 11:59:47AM

To see your man pages in PDF, search the whatis database etc., try my app (includes shell scripts).
versiontracker link:
http://www.versiontracker.com/dyn/moreinfo/macosx/24301



[ Reply to This | # ]
PDF Unix manpages with Whatis Command Finder
Authored by: koncept on Dec 11, '04 07:43:49PM
So see them as PDF, you simply need this: man2pdf () { man -t $1 >/tmp/$$.ps && open /tmp/$$.ps } Preview will convert the .ps to PDF on-the-fly and open it.

[ Reply to This | # ]
Read Unix manpages in Safari via the shell and Bwana
Authored by: farranco on Dec 11, '04 07:11:52AM

the new version of Bwana allows you to change the AppleScript that is called for Safari. Allowing you to change it to fit your needs, with tabbed or new window browsing, with the above scripts for example.



[ Reply to This | # ]