7

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).

  • Why don't you use troff? It is free. – schily Dec 2 '15 at 15:36
  • I don't know how to, I learnt how to use groff by reading some answers on this site and related sites. If you write up an answer involving troff I'll may accept it, depending on the quality of the other answers to this question. – BH2017 Dec 2 '15 at 15:38
  • why not submit a bug report to sabayon and get them to fix their bugs? – cas Dec 3 '15 at 0:35
  • @cas The first link (the PNG rendering issues) is to a Sabayon bug report I filed around the time I asked this question. – BH2017 Dec 3 '15 at 0:57
  • try finding and fixing the source of the warning: can't find font `b' message - that may be the cause as the png files created tend to be just text in graphical format. possibly a missing font package that needs to be installed. – cas Dec 3 '15 at 1:13
6

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:

  • Ah, I should clarify I'm not just interested in the name of the programs, I'm interested in precisely how to use them to convert man pages to HTML. So please pick at least one of these programs and show me how to convert man pages to HTML with it. – BH2017 Dec 2 '15 at 15:21
  • Thanks for the edit, much better! I have a couple of questions though. Why would you redirect stderr to the html file in the man2html example? And why redirect to a file in /var/www/html? There's no need for a webserver, just redirect to a local file and you can point your browser to it. Also, did you check your man2html output? I tried it on my Arch and it doesn't produce formatted output. – terdon Dec 2 '15 at 15:38
  • No need to redirect stderr, ignore that :-). I've redirected it to /var/www/html so I can view the results during my tests (I'm using a remote system over ssh). You don't have to - using a browser locally works just fine. I have checked both - and they look OK on my system. Didn't check if they can produce PNG (or whatever the issue was with Arch) though. – Criveti Mihai Dec 2 '15 at 15:41
  • I like this answer I think I will end up accepting it, but there is one last issue with this answer. See Sabayon uses manpages in .bz2 format instead of .gz, so could you possibly rewrite your answer accordingly? Like modify the zcat lines with ones that will work with bzip2-compressed man pages. – BH2017 Dec 2 '15 at 15:55
  • man2html needs nroff output and does not work in trodd input Your example is wrong. – schily Dec 2 '15 at 15:56
5

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

enter image description here

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.

4

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 in the late 1990's. 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 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

When I needed to convert this to HTML, some five 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.

1

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.

  • Ah, you beat me to it! I just installed heirloom-doctools as well. Had to fiddle mk.config :-). – Criveti Mihai Dec 2 '15 at 16:06
0

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).

  • As mentioned before: man2html takes nroff output as it's input, you thus cannot give it a man page source file as input. – schily Dec 3 '15 at 10:26
  • 1
    @shily That depends on which man2html you're talking about. – Kaz Jan 4 '16 at 15:47
  • > 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. Look here: kylheku.com/cgit/man/log – Kaz Jan 4 '16 at 15:52

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.