From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp-4.sys.kth.se (smtp-4.sys.kth.se [130.237.48.193]) by krisdoz.my.domain (8.14.5/8.14.5) with ESMTP id s2VJeOeJ015153 for ; Mon, 31 Mar 2014 15:40:24 -0400 (EDT) Received: from mailscan-3.sys.kth.se (mailscan-3.sys.kth.se [130.237.48.170]) by smtp-4.sys.kth.se (Postfix) with ESMTP id F2908C9D; Mon, 31 Mar 2014 21:40:22 +0200 (CEST) X-Virus-Scanned: by amavisd-new at kth.se Received: from smtp-4.sys.kth.se ([130.237.48.193]) by mailscan-3.sys.kth.se (mailscan-3.sys.kth.se [130.237.48.170]) (amavisd-new, port 10024) with LMTP id JDf6eAgbhKif; Mon, 31 Mar 2014 21:40:17 +0200 (CEST) X-KTH-Auth: kristaps [85.3.59.60] X-KTH-mail-from: kristaps@bsd.lv Received: from [192.168.1.105] (60-59.3-85.cust.bluewin.ch [85.3.59.60]) by smtp-4.sys.kth.se (Postfix) with ESMTPSA id 6CDD51FFD; Mon, 31 Mar 2014 21:40:11 +0200 (CEST) Message-ID: <5339C49A.7020502@bsd.lv> Date: Mon, 31 Mar 2014 21:40:10 +0200 From: Kristaps Dzonsons User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:24.0) Gecko/20100101 Thunderbird/24.4.0 X-Mailinglist: mdocml-discuss Reply-To: discuss@mdocml.bsd.lv MIME-Version: 1.0 To: Ingo Schwarze CC: discuss@mdocml.bsd.lv Subject: Re: pod2mdoc, docbook2mdoc References: <53386109.9000504@bsd.lv> <20140331090912.GW26456@danbala.tuwien.ac.at> <533943B9.5080901@bsd.lv> <20140331161315.GC31866@iris.usta.de> In-Reply-To: <20140331161315.GC31866@iris.usta.de> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit > I wouldn't worry too much about that. The version number 0.0.5 > is telling enough, and the package description can say a few words > too. So i see no big risk there, but possible benefit allowing > cleaner packaging, installation and deinstallation of experimental > tools. Ingo, Thank you for your input! This looks logical to me. I'll drop a note here when I bump versions in a meaningful way--does that work? Note for those with commit access that the modules are in /usr/vhosts/mdocml.bsd.lv/pod2mdoc and so. (The commit hook in CVSROOT should probably be updated to mail commits on the new modules...) >> pod2mdoc works over all the POD >> I found (not being a Perl junkie, however, I just used what's in the >> Perl distribution), but docbook2mdoc still needs a lot of work. > > Indeed. As far as i can see, the biggest problem right now is that > it usually exits in the middle of each processed file, rendering > merely the beginning. To be usable, it has to become more resilient. Yes. This is because I don't support a huge set of docbook elements yet--and the parser exits when it encounters an unknown one to spur me to add as many new ones as possible. My plan (as you've noted below) is to start by having it accept all of doclifter's DocBook, then focus on the rest, possibly relaxing the parser to accept unknown nodes if we get lazy. Fortunately, it's easy to add new nodes to docbook2mdoc! They need an entry in extern.h, then the rules of parenting (this is the most annoying part--both children and parents need to be added in) in rules.c, then a handler in pnode_print(). Most handler types have already been implemented, so it's just putting together the blocks and going by example. Attributes work more or less the same way. > At first sight, it seems that the "ps->stop = 1;" in the > function xml_elem_start() cause the problem, but i didn't > try to come up with a fix yet. > > cvs.1.xml:33:6: unknown node "indexterm" > lynx.1.xml:83:0: unknown node "literallayout" > sqlite3.1.xml:108:0: unknown node "markup" This is by design--it just means that I need to add a NODE_INDEXTERM, etc. As mentioned, I'm going to start with doclifter's nodes. >> Fact is, I just don't know the "real world" landscape of ports using >> docbook (or POD, for that matter). Would it not be better to have >> somebody using (or porting) POD or DocBook systems to break them in >> before putting them out for general consumption? Thoughts? > > A good corpus of test input would be the man(7) manuals in OpenBSD > base, imho. As far as these are POD input, they are good testing > candidates for pod2mdoc; i consider the test chain POD -> pod2man -> > man(7) -> doclifter -> DocBook-XML -> docbook2mdoc mostly useless. > As far as they are real man(7), not from POD, they are good testing > candidates for docbook2mdoc, i.e. using the testing chain > man(7) -> doclifter -> DocBook-XML -> docbook2mdoc -> mdoc(7). > > At least at first, i think the main use for docbook2mdoc will > be as a postprocessor for doclifter, so getting it to handle > the subset of DocBook-XML produced by doclifter is the second > most useful step to take after preventing it from exiting > prematurely (see above). Agreed! > In any case, docbook2mdoc seems much more useful than pod2mdoc, > at least in a short-term perspective. My general thought on pod2mdoc was to avoid invoking perl(1) just to run pod2man(1) in the normal chain of looking at POD documents. I also thought that, with a few more pod2mdoc smarts, we'll be able to deeply mine those documents with mandocdb. From what I understand, they're kinda opaque right now. Best, Kristaps -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv