How do I convert Linux man pages to HTML without using groff?

Question

I would like to convert some Linux man pages to HTML without using groff. My prejudice against groff is due to some PNG rendering issues it is giving me that seems to be localized to Sabayon (as these issues do not seem to occur on my VirtualBox VMs for other distros). I realize this is a bug, but a solution seems to not be in the near future so I would like to ask if there are other ways to convert Linux man pages to HTML. Using the HTML pages at http://linux.die.net/man is not an acceptable solution as some of the man pages I am interested in are not there (e.g., emerge(1) is not there).

Answer 1

There are plenty of alternatives such as roffit, troff, man2html. There's also perl based online manpage browsers, such as manServer.

My favorite is pandoc, though sadly it doesn't seem to support ROFF input by default (though you can probably use it if you need to chain multiple transformation filters together.

man2html example:

zcat /usr/share/man/man1/dd.1.gz \ 
    | man2html \
    | sudo tee /var/www/html/dd.html

roffit example:

git clone git://github.com/bagder/roffit.git
cd roffit
zcat /usr/share/man/man1/dd.1.gz \
    | perl roffit \
    | sudo tee /var/www/html/dd-roffit.html

Other tools:

• troffcvt does about the same thing.
• The 'real' troff - Gonna try out http://heirloom.sourceforge.net/doctools.html. I suspect schily has OpenSolaris and friends in mind :-).

Answer 2

This first bit is a shameless rip from the official website:

mandoc is a suite of tools compiling mdoc, the roff macro language of choice for BSD manual pages, and man, the predominant historical language for UNIX manuals. It is small, ISO C, ISC-licensed, and quite fast. The main component of the toolset is the mandoc utility program, based on the libmandoc validating compiler, to format output for UNIX terminals (with support for wide-character locales), XHTML, HTML, PostScript, and PDF.

mandoc has predominantly been developed on OpenBSD and is both an OpenBSD and a BSD.lv project. We strive to support all interested free operating systems, in particular FreeBSD, NetBSD, DragonFly, illumos, Minix 3, and GNU/Linux, as well as all systems running the pkgsrc portable package build system. To support mandoc development, consider donating to the OpenBSD foundation.

pacman informs me my locally installed mdocml package-size is 3.28mb, and that it includes the following /usr/bin located binaries:

/usr/bin/demandoc
/usr/bin/makewhatis
/usr/bin/mandoc
/usr/bin/mapropos
/usr/bin/mman
/usr/bin/mwhatis

With it I can do:

mman -Thtml mman >/tmp/html
firefox file:///tmp/html

---

You can apply your own stylesheets as you like. All of the documentation is online, as well. And all of that, as I think, is compiled with mandoc as well.

Answer 3

Firstly, it should be noted that there is more than one program called man2html.

One utility called man2html is a C program originaly written in the late 1990's by Richard Verhoeven at the Eindhoven University of Technology. The program has substantially quirky internals. However, it has the advantage that it works with the raw man page source, rather than troff or nroff output. This program was added to Frederico Lucifredi's man suite.

The program understands the semantics of the man and mandoc macros, and outputs a reasonable HTML structure. For instance when you use indented paragraphs, like this:

.IP word
Definition of
word.
.RS

the program will put out a HTML definition list.

I maintain one very large man page (most of a megabyte of source, and nearly 400 800 pages long, when converted to letter size PDF by groff):

$ ls -l txr.1
-rw-rw-r-- 1 kaz kaz 980549 Jan  3 11:38 txr.1
-rw-rw-r-- 1 kaz kaz 2016633 Apr  7 16:00 txr.1

When I needed to convert this to HTML, some five ten years ago, the only thing I found which did a reasonable job was the man2html C program, plus post-processing of its output to "season to taste".

Eventually, I wanted a much better quality HTML document, so I started writing troff macros. The limitations of the C program became painfully apparent, so I forked it. On my git site, you can find a git repo with 30 patches to man2html. These patches fix a number of bugs, and enhance the program with a much improved ability to interpret troff macros, conditionals, loops and other constructs. I also added a M2 register by means of which you can write code which detects that it's running under man2html and can conditionally do some things differently (scroll down for an example). As well, I added a .M2SS command which lets you emit a custom HTML header section.

My large manpage is hosted here. This is produced with man2html, post-processed by my genman.txr program, which rearranges the sections, and adds hyper-links throughout the document. It also rewrites the internal links in the table of contents to be stable URLs (based on hashing rather than arbitrary enumeration) and makes the table of contents collapsible via some Javascript.

The exact commands used by my Makefile:

man2html txr.1 | ./txr genman.txr - > txr-manpage.html
tbl txr.1 | pdfroff -man --no-toc - > txr-manpage.pdf

For an example of how the output is conditionally different between HTML and nroff we can look at a section of the man output:

       9.19.4 Macro defstruct

       Syntax:

                (defstruct {<name> | (<name> <arg>*)} <super>
                   <slot-specifier>*)

              The  defstruct  macro defines a new structure type and registers
              it under <name>, which must be a bindable symbol,  according  to
              the  bindable  function. Likewise, the name of every <slot> must
              also be a bindable symbol.

Above, note how parameters are denoted in <angle> <brackets>. In the HTML version, they appear in italics.

The syntax section appears in the source code like this:

.coNP Macro @ defstruct
.synb
.mets (defstruct >> { name | >> ( name << arg *)} < super
.mets \ \  << slot-specifier *)
.syne

which is all custom macros defined in the same document. Under .mets, < b means b is a meta-syntactic variable. >> a b means a is a concrete syntax, next to which is the meta-syntactic b without any intervening space, and <> a b c means b is a meta-syntactic crunched between a and c literals.

My improved version of man2html understands the fairly complicated macro which implements these markup conventions.

Also, note how the manual has automatically numbered sections: that's all done by troff code, which man2html understands.

Answer 4

OP's problems with PNG-files match my experience using groff for xterm's manual page and control-sequences documentation. The problem is that groff is attempting to render tables as an image clipped from the PDF file, and that it has been buggy for several years. While I've used the Perl script man2html since the 1990s for ncurses documentation, for other programs I found it simpler to generate ad hoc html and pdf files using groff. PDF files work fine; the html files do not.

At the same time, the Perl script had its own problems.

Since neither was going away (and because the alternatives suggested have not been an improvement, due to adding dependencies or introducing other limitations), I resolved the problem by making improvements to man2html (on top of those which I had made over the course of several years) and added a new configure script option for each program to allow using groff as a default manpage to html converter, but using man2html when I set the option. Having done this, I removed all of the groff-generated html files this year from my website. There's a "man2html" page on the website documenting this; the actual script is available on my miscellaneous scripts page.

Some of the suggestions and comments appear to not have noticed that there are (at least) two programs named man2html:

• the Perl script by Earl Hood (linked by @criveti-mihai), and
• a C program originally written by Richard Verhoeven (and assumed in the example given by @criveti-mihai).

The C program does its own formatting, does not rely upon nroff/groff/whatever. It can read a manpage from the standard input, or as an actual file (among other things -- see its manual page). Given an nroff-syntax manual page "foo.1", you could format it using any of these commands:

man2html - <foo.1 >foo.1.html
cat foo.1 |man2html - >foo.1.html
man2html foo.1 >foo.1.html

The Perl script reads formatted manual pages, e.g., from nroff (which for OP's question is a wrapper for groff). You could use it like this:

nroff -man foo.1 |man2html >foo.1.html

I investigated using the C program as an alternative to the Perl script, but discarded it because

• it does not do a good job of formatting the output. In a quick check with ncurses's terminfo.5 file, I can see errors in the output formatting.
• the C program has a built-in notion of the manpage macros which does not cover the various cases (including writing new macros) which I need for the manual pages on my website.

Incidentally, it does handle the multiple redirects used in this file (which is a problem with legacy troff — the reason the ncurses installation instructions have advised using groff for the past 20 years).

Answer 5

Since OpenSolaris was made available as OSS, there is a free troff.

A set of ported sources are here:

http://heirloom.sourceforge.net/doctools.html

but Heirloom is a dead project since aprox. 2007. You may like to check

https://github.com/n-t-roff/heirloom-doctools

where some people continue the dead heirloom project.

Together with man2html, troff allows you to auto-create nice html man pages.

See e.g. the SchilliX man pages:

http://schillix.sourceforge.net/man/

with the Schily Bourne Shell:

http://schillix.sourceforge.net/man/man1/bosh.1.html

I am happy with this and with the right options, you get linked man pages to other documentation from the same group. I use e.g. this command:

soelim sh.1 | tbl | nroff -u1 -Tlp -man - | col -x | \
                        (sed -e 's/XXX/sh.1/g' ../conf/pre.html; \
                        man2html  -cgiurl '../man$section$subsection/$title.$section$subsection.html' -compress -nodepage; \
                        cat ../conf/post.html) | \
                        egrep -v 'HTML|BODY'> sh.1.html

that is part of the make file system in the schily tools. Note the files ../conf/pre.htmland ../conf/post.htmlfrom the schily makefilesystem that are needed for the title and others. You may like to change this four your needs.

An enhanced man2thml is part of the schily tools (see bottom of the bosh man page).

BTW: a funny information: the whole troff source code plus all sources for all helper programs like soelim, tbl, ... plus the man program source is only half of the code you need for the mandoc program and mandoc has only a very limited tbl support that breaks most Solaris man pages.

If you need support for mandoc formatted troff sources from FreeBSD and similar, I created a set of mandoc macros that work for troff. Check the SchilliX sources at: https://sourceforge.net/p/schillix-on/schillix-on/ci/default/tree/usr/src/cmd/troff/troff.d/tmac.d/ The code in question is in the files andoc and doc*.

The man program sources in SchilliX-ON have been changed to call nroff -mandoc instead of nroff -man.

Answer 6

For converting a man I use:

zcat "/usr/share/man/man1/${PROGRAM}.1.gz" | manly > "out.html"

For displaying a man direclty as html I use:

oman "${PROGRAM}"

The output looks like:

Answer 7

man -Hcat SomeCommand > SomeCommand.html