[Date Prev][Date Next]
Re: (ITS#7614) Markup error in slapd.conf.5
Eric S. Raymond wrote:
> Howard Chu <firstname.lastname@example.org>:
>> 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/