Hi all, Over the last couple weekends, I've been working on converting yelp- check to Python. I've basically hit feature parity (with caveats), and it's now in git. It hasn't yet replaced yelp-check, but you can test it, and I'd appreciate if you did.
First, grab from git: git clone [email protected]:GNOME/yelp-tools.git Then, anywhere you'd normally call yelp-check, instead call python3 with the path to tools/yelp-check.py. For example: python3 yelp-tools/tools/yelp-check.py links \ gnome-user-docs/gnome-help/C There are two things that are different: 1. There's no support for DocBook's entityref attributes, because I didn't see an API in lxml to resolve unparsed entity references, and honestly I don't think I've ever seen anyone use entityref in my 20 or so years of working with the format. 2. It's considerably more strict about orphans in Mallard sites. This probably doesn't affect anybody but me, and the new behavior is arguably more correct. If you've read this far, here's some reasoning behind this change. When I first wrote yelp-tools, and gnome-doc-utils before that, I tried really really hard to keep its dependencies super low to eliminate barriers to adoption. Building GNOME has a different affair back then. So I wrote in sh and awk, and avoided GNUisms whenever they were pointed out to me. I learned *a lot*. Now we have a build system written in Python. Python is everywhere. Nobody is balking at a tool because it uses Python. Why am I still writing in sh and awk? But also, it's only worth converting if there are advantages going forward. So here they are: * The new Python script is a bajillion times faster. * I can make Ducktype just work without an extra conversion step. * I intend to add a config file parser now, and then: * We'll be able to specify default options for commands. * We'll be able to run multiple checks with a single command. * We'll be able to generate reports, which can be run on CI. * We'll be able to do custom commands, replacing the kind of stuff we have now in gnome-help.sct. The last point is worth talking about more. Right now, gnome-help.sct has Schematron rules like this one: <rule context="mal:page/mal:info"> <assert test="normalize-space(mal:desc) != ''" >Must have non-empty desc</assert> </rule> Not bad, pretty straight-forward. Then you run an xmllint command that you can find in a comment at the top of the file. It works. My plan is that a yelp-check.cfg file can contain this: [desc-non-empty] Select = /mal:page/mal:info Assert = normalize-space(mal:desc) != '' Message = Must have non-empty desc And then you could run: yelp-check desc-non-empty Anyway, long email over. Please test the new Python script. Thanks, Shaun _______________________________________________ gnome-doc-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/gnome-doc-list
