Use Mallard as source for man pages?

Hi Mario,

On Fri, 2018-12-28 at 22:35 +0100, Mario Blättermann wrote:
> Hello,
> 
> the Glabels project [1], which resides in the Gnome Git repository
> for
> years, is currently to be ported to Qt5 [2]. Because the user
> interface is similar to the old GTK one, we want to reuse the
> existing
> user manual (at least partially). So Glabels-qt could become the
> first
> Qt project which uses Mallard as source for the user manual. Luckily,
> neither itstool nor yelp-tools seem to have any hard GTK/Gnome
> dependencies, which makes it much easier for a pure Qt project.

Awesome. It was definitely intentional to make those tools independant
so they can be widely used. I know itstool is used quite a bit outside
of GNOME, but yelp-xsl/yelp-tools not as much.

> Besides that, we want to reuse and extend the existing manpages.
> Groff
> itself is not very attractive, so we are looking for a simpler way.
> Markdown came closer, but it seems to be no more than a "poor man's
> XML" and almost unusable regarding i18n. Docbook is too complicated
> in
> comparison with Mallard, so the latter could be the less painful way,
> if possible. Would be nice if we had the same syntax for both user
> manual and traditional man pages, wouldn't it? Moreover, we can use
> the mentioned itstool/yelp-tools for both without bothering with
> different tools.
> 
> Essentially, we need a proper way to convert Mallard to Groff, using
> an appropriate stylesheet. Any help would be very appreciated.

I'm afraid I don't have anything already made for that. Based on my
experience from writing (then rewriting) the man parser in Yelp, I
think a 90% solution for converting TO roff from Mallard would be a
weekend job. Then there would be a very long tail of corner cases. I
might be able to throw a weekend at it after I get Mallard 1.1 out.

--
Shaun