Re: yelp-check validate noise

[Shaun McCance <shaunm gnome org>]

On Tue, 2022-02-01 at 23:02 +0100, Gunnar Hjalmarsson wrote:
> Hi!
>
> Lately, when running "yelp-check validate", the output includes
> things 
> which smell false positives. Example:
>
> gnome-help/C$ yelp-check validate --strict \
>  > --allow http://www.w3.org/2005/11/its \
>  > --allow http://www.w3.org/1999/xlink \
>  > --allow http://projectmallard.org/experimental/ \
>  > shell-overview.page
> shell-overview.page:4: element page: Relax-NG validity error :
> Expecting 
> element title, got info
> shell-overview.page:4: element page: Relax-NG validity error :
> Element 
> page failed to validate content
> shell-overview.page fails to validate
>
> Why would it matter if <info> appears before <title>? Maybe it's the 
> "allow" list which needs an update. Would appreciate your advice how
> to 
> use "yelp-check validate" properly.
>
> Using yelp-tools version 41.0.

This has to do with the way that xmllint handles RNG pattern matching.
Basically, if anything inside the info element is invalid, it causes
the entire info element to not match the mal_info pattern, and that's
all that xmllint reports.

jing is a lot better at showing the errors deeper in the pattern. You
can use jing instead by passing --jing to yelp-check. It looks like
jing is no longer in Fedora, but if I'm reading the internet right it's
still in Ubuntu universe.

The problem with that command on that page, by the way, is that the
namespace for the uix:thumb element is 

  http://projectmallard.org/experimental/ui/

not just

  http://projectmallard.org/experimental/

Change the --allow and it validates.

FUN CONTRIBUTION FOR PEOPLE WHO FIND THIS FUN: This annoyingly vague
error is pretty much always "Expecting element title, got info". No
other RNG patterns in the Mallard schema seem to trigger this. We can
probably just detect that in the xmllint stderr. But what can we do
about it? Make info required. The info element is optional in Mallard,
but if you make it required, you get way better errors. yelp-check
already rewrites the schema. We could detect this error, rewrite the
schema with info required, and call xmllint again. Probably not that
hard. Send me an MR. I'll buy you lunch whenever we can finally see
each other in person again.

--
Shaun