ManKier is now about 3 years old, but its core has changed substantially in the last year.
Originally, HTML man pages were created using doclifter: this outputs
DocBook XML, which was then converted to the HTML used on mankier.com. This toolchain worked to some extent, but with
increasing limitations and corner cases — workarounds started to pile up. I tried working with the doclifter source.
It's all one massive file, even after splitting it up into modules I struggled to properly grok it. Finally,
doclifter outputs DocBook XML, and I needed HTML.
So I wrote a troff parser.
Sure, I could just run something like
groff -m mandoc -Thtml ls.1 > ls.html
but that just translates presentational troff macros into a rough HTML equivalent - the great thing doclifter does is
translate the presentational troff into semantic markup. Semantic markup, as well as
being better for accessibility, makes it possible to do more with the renderings. For example, if we can identify an
option definition, we can make that option an anchor (e.g.: rg -F), and provide a way to
quickly explain what a bunch of options do.
Writing a troff parser has some easy wins, as most man pages use the man macros. For
.TH LS 1
do them all!
translates nicely to this HTML5:
<dd>do them all!</dd>
But troff has been around for decades, and can also get pretty gnarly. wireshark(1), for instance, does this:
.ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.ds #V .6m
.ds #F 0
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
To write “Jörg Mayer”. I think somebody had a lot of fun with that one. I should perhaps have paid more heed to this
comment before trying to disentangle it:
.\" Fear. Run. Save yourself. No user-serviceable parts.
Fortunately those pages also give an alternate string definition “for low resolution devices”, which just gives us
And if you like puzzles, check out the recursive .Xf macro defined in rc(1):
.if t .ds Cf C
.if n .ds Cf R
.\" Rc - Alternate Roman and Courier
.Xf R \\*(Cf \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
.if "\\$1"I" .if !"\\$5"" .ds Xi \^
.if !"\\$4"" .Xf \\$2 \\$1 "\\$3\\f\\$1\\$4\\*(Xi" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
.if "\\$4"" \\$3\fR\s10
.Rc ( & ).
This will simply output “(
&)” or “(&)”, depending on whether your formatter is troff or nroff.
If you want to find out more, groff(7) is the “short” reference which can elucidate the two
gnarly examples above.
ManKier's parser can now generate HTML5 for 99.98% of man pages. If you spot any pages that render horribly on
mankier.com, do drop me an email.
Getting this far has certainly been challenging, but also of course rather rewarding. Next step is to get that up to
100% — there are still a handful of esoteric troff requests to implement!