Converting the Xenocara manpages

[Stephen Gregoratto <dev@sgregoratto.me>]

Since you mentioned converting the DocBook files in the Xenocara tree
on Undeadly, I thought I'd take a quick stab at converting some of them
myself. To start, I'm only going to focus on <refentry> manpages. A
quick recursive grep shows that there are only 47 of these. Some notes:

One particularly bad case is lib/libXcomposite/man/Xcomposite.xml.
It starts as a <reference>, a collection of <refentry>'s. This is
strange considering that it only has one: Xcomposite(3). docbook2mdoc
renders this as one big, bold string. Piping just the refentry node
to docbook2mdoc is almost perfect: the only error is encountering the
unknown "<void />" element, which would we would output as .Ft void.
Might make a patch for this later.

All of the sgml files in dist/fontconfig/doc contain more than one
refentry node (funny considering that this is where a <reference> would
be useful). Only the first node gets its own ".Dd .Dt .Os" preamble
with the headers/text of subsequent nodes tacked on after. There are
some approaches on how new refentry nodes could be handled:

  1. Reset the parser and print another unique preamble. The resultant
  output could be split using a regular expression (e.g. perl or
  chaining awk+sed). I've tested csplit from the GNU coreutils which
  does this and it works quite well.

  2. Reset the parser and write to a new file. I can already imagine
  this being a PITA to implement and changes the program from being
  a simple input filter to a full blown converter, so I don't think
  this is the best choice.

  3. Split the sgml file itself using the method in approach 1 and
  run docbook2mdoc over each.  No code needed then :).

Many files reference variables that are set by autoconf. Some of them
could be stripped out (e.g. version numbers) whilst others can should
be replaced entirely (e.g. the *mansuffix variables).

Anyway, that's all I've got for now. If you're not actively working
on it, I might send a patches to tech@ for some edited conversions
of these files. The only problem I would have is how deep autoconf
integration should be (i.e. using @VARIABLES@) for the new files.
But I'll cross that bridge when I get there.
-- 
Stephen Gregoratto
PGP: 3FC6 3D0E 2801 C348 1C44 2D34 A80C 0F8E 8BAB EC8B
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv