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 s33CXrFs006735 for ; Thu, 3 Apr 2014 08:33:54 -0400 (EDT) Received: from mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) by smtp-4.sys.kth.se (Postfix) with ESMTP id 4340D1E08 for ; Thu, 3 Apr 2014 14:33:53 +0200 (CEST) X-Virus-Scanned: by amavisd-new at kth.se Received: from smtp-4.sys.kth.se ([130.237.48.193]) by mailscan-1.sys.kth.se (mailscan-1.sys.kth.se [130.237.32.91]) (amavisd-new, port 10024) with LMTP id rzY7K8nYUaw2 for ; Thu, 3 Apr 2014 14:33:51 +0200 (CEST) X-KTH-Auth: kristaps [85.3.59.60] X-KTH-mail-from: kristaps@bsd.lv X-KTH-rcpt-to: discuss@mdocml.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 7898AE5 for ; Thu, 3 Apr 2014 14:33:51 +0200 (CEST) Message-ID: <533D552E.1080407@bsd.lv> Date: Thu, 03 Apr 2014 14:33:50 +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: discuss@mdocml.bsd.lv Subject: Re: pod2mdoc, docbook2mdoc References: <533943B9.5080901@bsd.lv> <20140331161315.GC31866@iris.usta.de> <5339C49A.7020502@bsd.lv> <20140331205736.GJ31866@iris.usta.de> <20140331213020.GD29643@danbala.tuwien.ac.at> <5339E423.9010007@bsd.lv> <20140331222118.GB15415@iris.usta.de> <20140331223147.GA17640@danbala.tuwien.ac.at> <533D4DE1.4030304@bsd.lv> <20140403121738.GA6386@danbala.tuwien.ac.at> In-Reply-To: <20140403121738.GA6386@danbala.tuwien.ac.at> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Thomas, Thanks for the suggestions! In general, most of these fall into the "Smarts" category. My aim is to start with simple markup and properness, then get into the smarty stuff. The biggest improvement since the last version is in non-library applications (e.g. libssl/src/doc/apps). > Some suggestions: > * foo() -> .Fn foo I know that pod2man does this--that'd be an easy smart. > * too many Ns before punctuation This is a big one, but complicated to handle properly. Getting the spacing right was really a nightmare. Consider: BB< bar> BB B> > and so on. pod2mdoc does fine with all but one combination noted in the manual. As mandoc(1) will ignore the superfluous "Nm", it's safer to leave it as-is than try to be smarter. > * section number is 1 instead of 3 (not sure how to detect that) perlpod says that, absent a suffix of ".pm", the manual should be considered a section 1. I guess that ".pod" should be treated similarly--can you verify that? I also have a #define for which section should be the Perl module section. OpenBSD has 3p. (And a note that pod2mdoc needs to be changed if it's redefined.) > * .Bd -literal + #include + Ed -> .In foo Yes, this is TODO for more Smarts. > * splitting up the functions in the SYNOPSIS the same way is probably too much effort? Same thing: more Smarts... > Related question: > How do people use Sy vs. Dv? I use Dv for preprocessor symbols and NULL. I've never used Sy on my own. A fairly low-hanging smart would be to decorate NULL. > I personally always mark up NULL as a Dv and similarly for most other > defined C symbols. Best, Kristaps -- To unsubscribe send an email to discuss+unsubscribe@mdocml.bsd.lv