tech@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Stephen Gregoratto <dev@sgregoratto.me>
Cc: tech@mandoc.bsd.lv
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 tech+unsubscribe@mandoc.bsd.lv

      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 \
    --to=schwarze@usta.de \
    --cc=dev@sgregoratto.me \
    --cc=tech@mandoc.bsd.lv \
    /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
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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).