What's the easy way to convert all man pages to html?

Question

Sixteen years into the 21st century I remain baffled that we still have to go out of our way if we want to see a man page

• rendered in a proportional font (that is, not Courier or similar)
• with links to other referenced pages

There are tantalizing web sites with HTML man pages that have links, like this, but I haven't found such a site with pages updated for the current version of macOS. And of course a web site won't show man pages for software you've installed via Homebrew, etc.

Is there a solution to this problem? I've looked and looked. This

function manp {
  man -t "$1" | open -f -a /Applications/Preview.app/
}

renders a page and shows it in Preview (after you wait for a PostScript interpreter to convert it to PDF), but you don't get live links.

The man page for man says:

HTML PAGES

Man will find HTML pages if they live in directories named as expected to be ".html", thus a valid name for an HTML version of the ls(1) man page would be /usr/share/man/htmlman1/ls.1.html.

I could write a script to convert all of the man pages everywhere on my system to HTML, but I bet someone has already done this. And I bet they have also solved the problem of rendering SEE ALSO references as links, which the man command apparently doesn't do.

Answer 1

Install Bwana which allows you to browse the man pages in your favourite browser.

To quote the page above "Just type "man:" followed by the man page you're looking for into your browser's URL field. Hit enter and let Bwana do the rest." It has live links.

Answer 2

bcat lets you pipe stdout to your default browser. An alternative to your Preview function would be:

bman () 
{ 
    : Display man page in default browser
    man $* | col -b | bcat
}

...or simply set man's pager:

export MANPAGER='col -b | bcat'
man grep

bcat works with any command that writes to stdout:

pbpaste  | bcat
make test | bcat
tail -n 1000 -f /var/log/messages | bcat

...etc.

It's a ruby-gem, so installation is as easy as:

gem install bcat

If "on the fly" conversion isn't sufficient, and you want to produce HTML all at once, or in advance, this post on Unix.se has a number of suggestions (sadly one of my favourite tools, the mighty pandoc, won't work for this...)

Answer 3

If you're already comfortable viewing man pages in the terminal environment with the man command, then !man some-other-command is a quick way to visit cross-referenced man pages. Really, ! is a feature of the pager, less, and can be used to run any arbitrary shell command, then come right back to where you were.

So maybe you don't even need anything I'm about to mention below.

That said, if you want a clickety-clickety interface to the man pages on your system, then Bwana or Dash are the way to go on a Mac. Bwana has a slight edge because it actually caches the rendered man page and Dash doesn't appear to. Dash is also paid and closed-source, which you might consider a downside.

Bwana still works fine for me on Catalina, no muss, no fuss. Your mileage may vary with later versions of macOS, but the source is available, so I believe it will have a long life. The way it works—by installing a URL handler for man: links—is pretty clever, too. This means you can type, for example, man:find in the location bar of whatever browser you already use, or open man:find in Terminal.

I like to add the following userstyle to URLs generated by Bwana, so the content is centered in the window:

@-moz-document regexp("file:.+Caches/Bwana/.*(?<!manindex-).html") {
body {
  max-width: 80ch;
  margin-left: auto;
  margin-right: auto;
}
}

Several other timeworn solutions exist which will work in a generic Unix environment, and that includes Mac. These may require you to set up a web server, though, because something has to respond when you click those links in the SEE ALSO section, after all.

There is even a project called manservant which wraps the Perl man2html in a small Ruby web application, solving the web server issue for you. Of the other ones mentioned here, this has the most pleasing visual style. You should be able to get this working without much trouble, just using the Ruby that comes with macOS, at least up to and including Catalina.