Re: Use Mallard as source for man pages?

[Mario Blättermann <mario blaettermann gmail com>]

Hi Shaun,

Shaun McCance <shaunm gnome org> schrieb am Fr., 11. Jan. 2019, 16:05:

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.

thanks for your answer and sorry for the extremely delayed replay. Unfortunately, Jim Evins (the maintainer of Glabels) has decided to switch from Mallard to Python Sphinx in the meantime. Admittedly, I'm not very happy with his choice, but he's the boss, and my knowledge about things like build system integration and format converters is quite poor...

Anyway, it would be fine to have a converter from Mallard to Groff. Then the existing man pages in Gnome applications (even those which are only available in Debian packages due to Debian's man page policy) could be converted to Mallard and integrated into the po file of the user manual. This way the doc translators don't have to think about whether they give man page translations a priority, they would have the appropriate gettext messages in the same file anyway. Moreover, nobody has to bother with changes in Damned Lies, for example additional lists for man pages.

Besides the converter itself, there's some yelp-tools magic needed to separate user manual and Groff stuff during the build process and installation.

Best Regards,

Mario