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 4724ae7e for ; Thu, 25 Apr 2019 13:33:13 -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 1hJjBH-0001gG-NZ; Thu, 25 Apr 2019 20:33:12 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1hJjBG-00080I-FD; Thu, 25 Apr 2019 20:33:10 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1hJjBG-0004lF-Bh; Thu, 25 Apr 2019 20:33:10 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 71730730; Thu, 25 Apr 2019 20:33:10 +0200 (CEST) Date: Thu, 25 Apr 2019 20:33:10 +0200 From: Ingo Schwarze To: Stephen Gregoratto Cc: tech@mandoc.bsd.lv Subject: Re: [PATCH docbook2mdoc] Add NODE_EMAIL Message-ID: <20190425183310.GB58311@athene.usta.de> References: <20190322103342.6idzehqruirutcog@BlackBox> <20190322200700.GD6535@athene.usta.de> <20190323053008.vctluoysjwtc3usv@BlackBox> <20190323084616.GA62193@athene.usta.de> <20190323101835.bqaltgzmfbnvxcfl@BlackBox> X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20190323101835.bqaltgzmfbnvxcfl@BlackBox> User-Agent: Mutt/1.8.0 (2017-02-23) Hi Stephen, Stephen Gregoratto wrote on Sat, Mar 23, 2019 at 09:18:35PM +1100: > I forgot to mention that I'll be publishing my findings on my blog. > I aim to write up an example user command/library call man-page, > porting them by hand to the different formats. I'll describe the > methods/programs used to validate/format/convert each format, Sounds potentially interesting, but also a lot of work. Many of the most important results are of course obvious from the outset, for example than mdoc(7) and DocBook are semantically more powerful than man(7), perlpod(1), Markdown, asciidoc and the like and hence conversion quality will be strongly asymmetric in both directions. That doen't necessarily mean that you won't find any non-trivial results, though. > and analyse the quality of the conversions. When analyzing validation and conversion quality, don't forget that both validation and conversion can have very different objectives and hence comparing them directly can be misleading. For example, in mandoc(1) and in the default DocBook toolchain, validation serves to help authors write good markup, whereas in docbook2mdoc(1) it is only intended to help docbook2mdoc(1) development. For example, the DocBook to man(7) conversion in the default DocBook toolchain, the perlpod(1) to man(7) conversion by pod2man(1), and the mdoc(7) to HTML conversion by mandoc(1) are production conversions that *every* document in the source languages is supposed to go through, so they ought to be held to highest standards. By contrast, the mdoc(7) to man(7) and to markdown conversions in mandoc are only auxiliary conversions to make the documents readable on inferior systems or in constrained environments, so they ought to be held to much lower standards; using them as a main production step wozuld be a terrible idea in the first place. And converters like pod2mdoc(1) and doclifter(1) are only intended for one-time conversions with manual postprocessing, so they should be held to an even lower standard. Conversion can have very different quality requirements. > I'll also see how it fares going through mandoc's HTML output, > groff's PDF output and the UTF-8 output of both. The result of the latter cannot be tested with a single input file. The output will likely be byte-by-byte identical, in particular when you write good input code. To compare the quality of groff and mandoc terminal output (including ASCII or UTF-8), you need to compare large corpusses of documents of diverse provinence, or the results won't be meaningful. > Finally, I'll ask each respective "camp" if they'd > like to comment on my findings, and include them at the end (that > means you, Ingo). Sure, ask me when you get to that point. > That's why I say good faith, I certainly don't want > to anger anyone from a different camp by hating their work right out > of the gate. That I can leave that up to you ;). Fine with me, i'll take care of that part. :-) Yours, Ingo -- To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv