I maintain a man-page-to-DocBook converter, doclifter. A side effect of this program is that it serves as a validator for the correctness and portability of the markup used on Unix manual pages. I test it by running it against all the manual pages in a full %s; there are %d of these on my development machine, of which %d already have DocBook masters. It converts %d (%02.2f%%) of the remaining %d into valid XML-DocBook.

Most of the remaining %02.2f%% of errors happen because groff(1) and its kin have weak-to-nonexistent validity checking. Often, doclifter fails because of outright errors in macro usage that groff does not catch. Sometime it fails on constructions that are legal but perverse. Very occasionally it throws an error because a man page is correct but has a structure that cannot be translated to DocBook. I keep a database of patches for such problems, and periodically try to push fix patches out to the manual-page maintainers.

(These are lower numbers and a higher error rate than in some previous reports because I now use i3 rather than GNOME or KDE. Many of the userland manuals that I used to check are no longer installed where my test procedure can see them. Because bad markup tends to be concentrated in the older manual pages of core tools, a larger random sample pulls down the error rate.)

Even if you do not care about DocBook, this cleanup work benefits all third-party manual page viewers, including the GNOME and KDE documentation browsers; groff constructions that confuse doclifter are very likely to produce visible problems on these.

The table below is a listing of the %d (%02.2f%%) pages on which doclifter fails, but the failure can be prevented with a fix patch to the manual page source. %d pages (%02.2f%%) remain intractable, generally due to markup problems more severe than a point patch can address. I am working with the individual projects responsible to get those cleaned up.

It is likely that you are reading this because you have received email telling you that patches are associated with your name or list address. Please consider incorporating them, or equivalents, in your next release. Also, please write back and tell me what you plan to do so I can keep my database up-to-date.

If you are not already considering it, please think about moving the documentation masters of your project to DocBook (or some format from which you can generate DocBook). If everybody moved to using DocBook as a common exchange format, it would become much easier to support unified browsing of all system documentation with Web-like hypertext capabilities, automatic indexing, and rich search facilities.

Tools to generate man pages, HTML, and PostScript from DocBook files are open-source and generally available. My program, doclifter, should make moving your manual-page masters to DocBook a fairly painless process.

Many major open source projects (including the Linux kernel, the Linux Documentation Project, X.org, GNOME, KDE, and FreeBSD) have already moved to DocBook or are in the process of doing so.

(Individual entries for accepted patches are no longer shown.)

Summary: %d patches pending, %d accepted, %d rejected.

Status codes are as follows:

n	No response yet.
p	Maintainer has informed me that this is fixed in the masters, but I have not seen the fix yet.
y	Accepted
r	Rejected
s	Superseded (page lifts correctly without the patch)
[0-9]+	number of mailings sent
b	Address is blocked

Problem codes are explained after the table.

''' % (time.strftime("%d %b %Y", time.gmtime()), buglist.distro, total, already, ok, percent(ok), total - already, 100.00 - percent(ok), applied, percent(applied), errors, percent(errors), pending, accepted, rejected) for line in bugs.lines: (status, pages, problems, mailto) = map(string.strip, line.split("|")) if 'g' in status: continue mailto = mailto.replace("<", "<").replace(">", ">").replace("@", "@") problems = " ".join(map(lambda x: "%s" % (x,x), problems)) pages = "
\n".join(map(lambda x: "%s" % (x,x), pages.split(",")))+"
\n" if 'p' in status or 'y' in status or 's' in status: status = "" + status + "" print "" % (pages,problems,status) print "

Patch:	Problem code:	Status:
%s	%s	%s

\n\n

Error codes:

%s: %s