Validation errors inside info elements

Jim Campbell <jwcampbell at gmail.com>
Thu Feb 23 12:29:29 EST 2017

Hi Shaun,

On Thu, Feb 23, 2017 at 9:27 AM, Shaun McCance <shaunm at gnome.org> wrote:

> 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
>
>
>
>
> _______________________________________________
> mallard-list mailing list
> mallard-list at projectmallard.org
> http://projectmallard.org/mailman/listinfo/mallard-list


This sounds like it will simplify the process of spotting the root of an
error in a Mallard document, which will be very helpful. Thanks for putting
this together,  And I agree on not making jing a hard dependency for
yelp-tools.

Cheers,

Jim
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://projectmallard.org/pipermail/mallard-list/attachments/20170223/d225fc71/attachment.html>