From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 771e75d9 for ; Sat, 20 Apr 2019 09:44:00 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1hHrDi-0001L1-VD; Sat, 20 Apr 2019 16:43:59 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1hHrDh-0002yq-So; Sat, 20 Apr 2019 16:43:57 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1hHrDh-0008GI-PZ; Sat, 20 Apr 2019 16:43:57 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 2c7899f4; Sat, 20 Apr 2019 16:43:57 +0200 (CEST) Date: Sat, 20 Apr 2019 16:43:57 +0200 From: Ingo Schwarze To: Stephen Gregoratto Cc: discuss@mandoc.bsd.lv Subject: Re: Converting the Xenocara manpages Message-ID: <20190420144357.GC45166@athene.usta.de> References: <20190420124345.22eynr3sxzu4ybgd@BlackBox> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20190420124345.22eynr3sxzu4ybgd@BlackBox> User-Agent: Mutt/1.8.0 (2017-02-23) 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 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 , a collection of '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 is unknown, so it gets ignored, and the first element within, , 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