Validation errors inside info elements

Shaun McCance <shaunm at gnome.org>
Thu Feb 23 10:27:15 EST 2017

tl;dr: `yelp-check validate --jing` is useful.

If you've used `yelp-check validate` much, you've probably run into
this annoyingly unhelpful message:

foo.page:3: element page: Relax-NG validity error : Expecting element
title, got info

This happens whenever anything is invalid anywhere inside the info
element, with no indication of what's actually wrong. Why does this
happen? Relax-NG is pattern-based, sort of like regular expressions for
element sequences. You could, in theory, have different patterns for
info elements with different content models, and allow just one of them
to appear. So the fact that the contents of info don't match doesn't
necessarily indicate a problem. Maybe something else will.

Because the info element is optional, libxml2 views any validation
errors inside info as knocking the whole info pattern out, and then
tries to match the actual info element against the next thing in the
sequence, which is a title. Hence, the useless error.

With a little bit of smartness, however, a Relax-NG validator can
recognize this kind of pattern and decide the info element really ought
to be matching the info pattern, because nothing else will, and then
report the inner errors.

It turns out the jing validator has this extra bit of smartness. So
I've just added the --jing option to `yelp-check validate`. Using that,
you'll get error messages like this:

foo.page:16:17: error: element "copyright" not allowed here; expected
the element end-tag, element "credit", "license", "link", "revision" or
"title" or an element from another namespace

I'm not making jing the default for a few reasons. One, I don't want to
introduce a hard dependency on the whole Java stack. (Distributors,
please don't make your yelp-tools package depend on jing.) Also, the
libxml2 code paths are well-tested, and I'm wary about introducing
different error reporting into people's workflows.

You'll need to install jing, of course. And you need it installed in a
way that actually puts a jing command in your $PATH. (AFAIK, this is
not the case with the upstream project, because Java developers are
weird. But the RPM in Fedora, at least, has a wrapper binary.)

This is in git right now. You can either build from git, or wait for
the next package to drop.

--
Shaun