Re: Converting the Xenocara manpages

[Ingo Schwarze <schwarze@usta.de>]

Hi Stephen,

Stephen Gregoratto wrote on Sat, Apr 20, 2019 at 10:43:45PM +1000:

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

That one is already installed as /usr/X11R6/man/man3/Xcomposite.3,
unless i'm mistaken.  The content seems to be very similar, if not
identical.

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

Right, i should fix that.  What happens here is that the document (= top
level) element <reference> is unknown, so it gets ignored, and the first
element within, <title>, becomes the document element.  Then the
<refentry> is *after* the document element, so it gets included *into*
the title because an XML file cannot have two top-level elements.
But an isolated <title> - i.e. one that isn't in a <section> or a
similar element - is converted to bold text, which isn't what we want
here.  You can see the misparsing with

 $ docbook2mdoc -T tree /usr/xenocara/lib/libXcomposite/man/Xcomposite.xml \
     | head -n 3
 /usr/xenocara/lib/libXcomposite/man/Xcomposite.xml:4:1: \
     ERROR: unknown element <reference>
 /usr/xenocara/lib/libXcomposite/man/Xcomposite.xml:74:4: \
     ERROR: unknown element <void>

 title
   (t) X Composite Extension Library
   refentry id='Xcomposite.man'

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

Yes, <void> needs to be implemented.

> All of the sgml files in dist/fontconfig/doc

It seems (at least part of) their content is already installed as manual
pages, see /usr/X11R6/man/man3/Fc*.3.

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

I tend to postpone that decision until we really need it.
All three options seem viable, i'm not yet sure which one
will be best for the specific needs that might arise.

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

Yes, that is among the final aspects to polish once we decide to
install specific files.  It will not be difficult to fix.

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

We should probably not start with files the content of which is already
being installed, unless we can show that what is being installed is
outdated and the newly converted versions are better.

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

We probably shouldn't waste time in autohell; instead, KISS.
All that is needed can probably be done easily in Makefile.bsd-wrappers.
But you are right build system questions are hardly a priority;
they can get sorted out once we know which files we want to install,
if any.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv