help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Stephen Gregoratto <dev@sgregoratto.me>
Cc: discuss@mandoc.bsd.lv
Subject: Re: Converting the Xenocara manpages
Date: Thu, 25 Apr 2019 20:03:23 +0200	[thread overview]
Message-ID: <20190425180323.GA58311@athene.usta.de> (raw)
In-Reply-To: <20190420144357.GC45166@athene.usta.de>

Hi Stephen,

Ingo Schwarze wrote on Sat, Apr 20, 2019 at 04:43:57PM +0200:
> Stephen Gregoratto wrote on Sat, Apr 20, 2019 at 10:43:45PM +1000:

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

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

The below commit is an easy fix for this issue.

Given the rarity of <reference>, i refrained from writing a full-blown
handler for it, at least for now.


Log Message:
Make <reference> an alias for <section>.

This is not perfect because if <reference> starts with a <title>,
that title is still printed before the NAME section.  But at least
the <refentry>s no longer get lumped *into* the <title>.

Issue found by Stephen Gregoratto <dev at sgregoratto dot me>
in Xcomposite(3).

Modified Files:

Revision Data
Index: parse.c
RCS file: /home/cvs/mdocml/docbook2mdoc/parse.c,v
retrieving revision 1.51
retrieving revision 1.52
diff -Lparse.c -Lparse.c -u -p -r1.51 -r1.52
--- parse.c
+++ parse.c
@@ -104,6 +104,7 @@ static	const struct alias aliases[] = {
 	{ "phrase",		NODE_IGNORE },
 	{ "primary",		NODE_DELETE },
 	{ "property",		NODE_PARAMETER },
+	{ "reference",		NODE_SECTION },
 	{ "refsect1",		NODE_SECTION },
 	{ "refsect2",		NODE_SECTION },
 	{ "refsect3",		NODE_SECTION },
Index: statistics.c
RCS file: /home/cvs/mdocml/docbook2mdoc/statistics.c,v
retrieving revision 1.35
retrieving revision 1.36
diff -Lstatistics.c -Lstatistics.c -u -p -r1.35 -r1.36
--- statistics.c
+++ statistics.c
@@ -368,6 +368,7 @@ main(int argc, char *argv[])
 		table_add("ROOT", "part");
 		table_add("ROOT", "preface");
 		table_add("ROOT", "refentry");
+		table_add("ROOT", "reference");
 		table_add("ROOT", "sect1");
 		table_add("ROOT", "sect2");
 		table_add("acronym", "TEXT");
@@ -527,6 +528,7 @@ main(int argc, char *argv[])
 		table_add("refentryinfo", "date");
 		table_add("refentryinfo", "productname");
 		table_add("refentrytitle", "TEXT");
+		table_add("reference", "refentry");
 		table_add("refmeta", "manvolnum");
 		table_add("refmeta", "refentrytitle");
 		table_add("refmeta", "refmiscinfo");
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

      reply	other threads:[~2019-04-25 18:03 UTC|newest]

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

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:

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

  git send-email \
    --in-reply-to=20190425180323.GA58311@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=dev@sgregoratto.me \
    --cc=discuss@mandoc.bsd.lv \
    --subject='Re: Converting the Xenocara manpages' \


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