discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Stephen Gregoratto <dev@sgregoratto.me>
To: discuss@mandoc.bsd.lv
Subject: Converting the Xenocara manpages
Date: Sat, 20 Apr 2019 22:43:45 +1000	[thread overview]
Message-ID: <20190420124345.22eynr3sxzu4ybgd@BlackBox> (raw)

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

             reply	other threads:[~2019-04-20 12:43 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-04-20 12:43 Stephen Gregoratto [this message]
2019-04-20 14:43 ` Ingo Schwarze
2019-04-25 18:03   ` Ingo Schwarze

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190420124345.22eynr3sxzu4ybgd@BlackBox \
    --to=dev@sgregoratto.me \
    --cc=discuss@mandoc.bsd.lv \
    --subject='Re: Converting the Xenocara manpages' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

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).