Re: Status of the yelp man-page parser

From: Brent Smith <gnome nextreality net>

To: esr thyrsus com

Cc: gnome-doc-devel-list gnome org

Subject: Re: Status of the yelp man-page parser

Date: Thu, 15 Feb 2007 18:34:41 -0700

Eric S. Raymond wrote:

I'm doing some work on the groff manual pages, trying to make sure
they render correctly through various programs such as man2html,
the KDE help broweser, manServer, and yelp.
Towards that end, I recently had a look at the yelp source code at
<http://cvs.gnome.org/viewcvs/yelp/src/yelp-man-parser.c?view=markup>.
My goal was to enumerate the sets of troff requests and escapes that
it interprets.

I left that page more puzzled than I arrived. It doesn't look to me
like that code is functional -- in particular, it looks like .if

conditionals and escapes in macro arguments aren't handled. And yet,
yelp seems to be doing a pretty good job of displaying man pages that
I know require these features.
Have I missed something here, or is yelp actually doing something

like calling groff behind the scenes?

How's this for a late response!

I was probably the last one to touch that code, and I must say that it
is all rather hackish and basically ignores basically all conditional
commands. Surprisingly it formats the majority of man pages fairly
well, but really it should be re-written the "right" way (I'm not quite
sure what the right way is). Ages ago there was a dependency on some
man2html program, but for reasons that are beyond me, it was re-written
to remove that dependency (I think I remember hearing maintainability as
being the major problem).

The parser converts the groff formats to an intermediate xml based
format, and then uses yelp's xslt "pager" system to convert the
intermediate xml format to HTML for display.

I've lost interest in it, so anyone's efforts to improve it or
completely rewrite it are welcome.