Eric S. Raymond wrote: > Howard Chu <[email protected]>: >> The patch changes much more than your bug report mentions. The error >> message you provide is pretty ambiguous, in particular you haven't >> mentioned exactly which markup element is out of order. Without this >> information we can't confirm what you're fixing. > > Globally, I'm trying to fix up the entire Linux manual page corpus so > it can be automatically lifted to clean HTML. I've been working in > this intermittently since 2002, and am not far from the goal. In > approximately 12,000 pages carried in stock Ubuntu, 94% now lift > without errors or warnings. For all but 17 of the 6% remaining I have > fix patches which I'm trying to get merged upstream. > > I entered one of those patches in your bugtracker, but failed to notice > that the error code in my bug database entry for slapd.conf.5 was > incorrect (failed to match the patch). I apologize for this; > full explanation follows. > > My conversion tool is doclifter, which you can read about at > <http://www.catb.org/~esr/doclifter/>. It lifts manual pages to > XML-DocBook, which in turn is very easily rendered to HTML. This > sequence produces better-quality HTML than tools like man2html > can generate, because of the amount of content analysis done > in the doclifter intermediate step.
> There are some legal troff constructions that doclifter cannot > parse well. These are the same sorts of things that any man-page > renderer other than groff itself is likely to get wrong; thus, they > are likely to confuse tools such as XMan, TkMan, and Rosetta as well > as doclifter. Hm. I use my own man2html http://highlandsun.com/hyc/man2html.c which gives pretty good looking output for us. Really, if you're developing a tool that claims to read troff input, it has to actually do so. I mean, the point of tools such as this is to be able to convert existing documents without modifying them, isn't it? > Thhe patch I sent you introduces an .EX/.EE macro pair for framing > code examples, a common extension often found on older Unix manual > pages (I believe it originated in DEC Ultrix). This macro > encapsulates a bunch of low-level troff operations that are hard to > lift well in isolation. There's a ruleset in doclifter that recognizes > .EX/.EE, analyzes the example content, and generates <programlisting> > or <literallayout> tags as appropriate. > > In some cases .EX/.EE replaces .RS/.RE pairs; in others it replaces > .nf/.fi pairs, in still others it replaces .TP, and I think there > are a couple of odd combinations of .RS/.RE with .TP in there too. The fact > that it has to mess with all of these is what makes the patch so > complex. But the result is simple: to express the "example" intention > better so it can be structurally translated. > -- -- Howard Chu CTO, Symas Corp. http://www.symas.com Director, Highland Sun http://highlandsun.com/hyc/ Chief Architect, OpenLDAP http://www.openldap.org/project/
