<div dir="ltr">Hi Shaun,<div class="gmail_extra"><br><div class="gmail_quote">On Thu, Feb 23, 2017 at 9:27 AM, Shaun McCance <span dir="ltr"><<a href="mailto:shaunm@gnome.org" target="_blank">shaunm@gnome.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">tl;dr: `yelp-check validate --jing` is useful.<br>
<br>
If you've used `yelp-check validate` much, you've probably run into<br>
this annoyingly unhelpful message:<br>
<br>
foo.page:3: element page: Relax-NG validity error : Expecting element<br>
title, got info<br>
<br>
This happens whenever anything is invalid anywhere inside the info<br>
element, with no indication of what's actually wrong. Why does this<br>
happen? Relax-NG is pattern-based, sort of like regular expressions for<br>
element sequences. You could, in theory, have different patterns for<br>
info elements with different content models, and allow just one of them<br>
to appear. So the fact that the contents of info don't match doesn't<br>
necessarily indicate a problem. Maybe something else will.<br>
<br>
Because the info element is optional, libxml2 views any validation<br>
errors inside info as knocking the whole info pattern out, and then<br>
tries to match the actual info element against the next thing in the<br>
sequence, which is a title. Hence, the useless error.<br>
<br>
With a little bit of smartness, however, a Relax-NG validator can<br>
recognize this kind of pattern and decide the info element really ought<br>
to be matching the info pattern, because nothing else will, and then<br>
report the inner errors.<br>
<br>
It turns out the jing validator has this extra bit of smartness. So<br>
I've just added the --jing option to `yelp-check validate`. Using that,<br>
you'll get error messages like this:<br>
<br>
foo.page:16:17: error: element "copyright" not allowed here; expected<br>
the element end-tag, element "credit", "license", "link", "revision" or<br>
"title" or an element from another namespace<br>
<br>
I'm not making jing the default for a few reasons. One, I don't want to<br>
introduce a hard dependency on the whole Java stack. (Distributors,<br>
please don't make your yelp-tools package depend on jing.) Also, the<br>
libxml2 code paths are well-tested, and I'm wary about introducing<br>
different error reporting into people's workflows.<br>
<br>
You'll need to install jing, of course. And you need it installed in a<br>
way that actually puts a jing command in your $PATH. (AFAIK, this is<br>
not the case with the upstream project, because Java developers are<br>
weird. But the RPM in Fedora, at least, has a wrapper binary.)<br>
<br>
This is in git right now. You can either build from git, or wait for<br>
the next package to drop.<br>
<br>
--<br>
Shaun<br>
<br>
<br>
<br>
<br>
______________________________<wbr>_________________<br>
mallard-list mailing list<br>
<a href="mailto:mallard-list@projectmallard.org">mallard-list@projectmallard.<wbr>org</a><br>
<a href="http://projectmallard.org/mailman/listinfo/mallard-list" rel="noreferrer" target="_blank">http://projectmallard.org/<wbr>mailman/listinfo/mallard-list</a></blockquote><div><br></div><div>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.</div><div><br></div><div>Cheers,</div><div><br>Jim </div></div><br></div></div>