discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
* Converting the Xenocara manpages
@ 2019-04-20 12:43 Stephen Gregoratto
  2019-04-20 14:43 ` Ingo Schwarze
  0 siblings, 1 reply; 3+ messages in thread
From: Stephen Gregoratto @ 2019-04-20 12:43 UTC (permalink / raw)
  To: discuss

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

^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2019-04-25 18:03 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-04-20 12:43 Converting the Xenocara manpages Stephen Gregoratto
2019-04-20 14:43 ` Ingo Schwarze
2019-04-25 18:03   ` Ingo Schwarze

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).