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 do fixup
passes on the man-page universe every few years; my last one was in
2007, an unusually long interval).
I'm currently testing my upcoming 2.9 release of doclifter by running
it against all the manual pages in a full Ubuntu 12.04 with some
extras; there are 13464 of these on my development machine. It
converts 11110 (96.87%) into valid XML-DocBook before patching.</p>
Most of the remaining 3.13% 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.
I currently have 27 patches queued for the X documentation, and based
on what's in my error logs expect to have over 200 before I'm done
this pass. None of them are large; almost all are trivial. The first
on my list, which adds table markup in order to banish a .ta request,
is representative of the larger ones. (Note the exiguous slash near
the beginning of the patch; my validator catches a lot of these.)
--- bitmap.1-unpatched 2012-06-25 14:31:56.221954441 -0400
+++ bitmap.1 2012-06-25 14:32:17.945954031 -0400
@@ -425,7 +425,7 @@
the specified filename is desired.
.TP 4
.B Quit
-\This command will terminate the bitmap application. If the file was
+This command will terminate the bitmap application. If the file was
not saved, user will be prompted and asked whether to save the image
or not. This command is preferred over killing the process.
.SH EDIT MENU
@@ -619,13 +619,16 @@
Class bitmapWidgetClass
Class Name Bitmap
Superclass Bitmap
-
+.fi
All the Simple Widget resources plus .\|.\|.
-.ta 1.6i 3.2i 4.8i
+.TS
+box;
+c c c c
+l l l l.
Name Class Type Default Value
-
+_
foreground Foreground Pixel XtDefaultForeground
highlight Highlight Pixel XtDefaultForeground
framing Framing Pixel XtDefaultForeground
@@ -648,7 +651,7 @@
button5Function Button5Function DrawingFunction Invert
filename Filename String None ("")
basename Basename String None ("")
-.fi
+.TE
I'm requesting commit access to the X repo so that nobody else
will have to pore through this boring crap in order to apply it.
--
<a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>
"...quemadmodum gladius neminem occidit, occidentis telum est."
[...a sword never kills anybody; it's a tool in the killer's hand.]
-- (Lucius Annaeus) Seneca "the Younger" (ca. 4 BC-65 AD),
_______________________________________________
[email protected]: X.Org support
Archives: http://lists.freedesktop.org/archives/xorg
Info: http://lists.x.org/mailman/listinfo/xorg
Your subscription address: [email protected]
