From: Ingo Schwarze <firstname.lastname@example.org> To: Stephen Gregoratto <email@example.com> Cc: firstname.lastname@example.org Subject: Re: [PATCH docbook2mdoc] Add NODE_EMAIL Date: Thu, 25 Apr 2019 20:33:10 +0200 [thread overview] Message-ID: <20190425183310.GB58311@athene.usta.de> (raw) In-Reply-To: <20190323101835.bqaltgzmfbnvxcfl@BlackBox> 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 email@example.com
prev parent reply other threads:[~2019-04-25 18:33 UTC|newest] Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top 2019-03-22 10:33 Stephen Gregoratto 2019-03-22 12:32 ` Ingo Schwarze 2019-03-22 20:07 ` Ingo Schwarze 2019-03-23 5:30 ` Stephen Gregoratto 2019-03-23 8:46 ` Ingo Schwarze 2019-03-23 10:18 ` Stephen Gregoratto 2019-04-25 18:33 ` 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: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20190425183310.GB58311@athene.usta.de \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --subject='Re: [PATCH docbook2mdoc] Add NODE_EMAIL' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * 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).