fix: the manual's figures carry a description, and the check that would have caught them
Three pages opened in nothing in Yelp -- overview (twice), math, trigger -- while every check passed. They are exactly the pages whose <figure> had a sentence for a <title> and no <desc>: a Mallard <figure> is title?, desc?, media, and the page is refused without the description. The idiomatic shape, as the shipped sets on this machine write it, moves the sentence into <desc> and leaves the <title> a name. Note trigger-capture.png is referenced from both overview and trigger, which is why those two pages are the ones that were noticed. The gap was in the check, not in its reach: tools/check_help.sh ran links/media/orphans/ids and an HTML render, and all four are silent about a page that is well linked, well parsed and unrenderable. `yelp-check validate` is the one that would have caught it, and it cannot run here: it generates the RelaxNG schema with xsltproc, but the schema includes the base grammar over the network and this machine's libxml cannot fetch. So the structural rules this project has actually needed are checked with xmllint's XPath, offline, each written after a page needed it. One trap, paid for while writing it: a Mallard page declares xmlns="http://projectmallard.org/1.0/", XPath 1.0 has no default namespace, so `//figure` matches nothing and every rule passes -- the first version of this check reported "ok" for the very defect it was written for. Every expression uses local-name() for that reason, and the script says so where the next reader will be. Verified: on the committed pages the rules exit 1 and name the three figures, which is the failing-before case kept as the regression test; on the fixed pages all five rules pass and yelp-build renders all 15; make -C build test-help goes from red to green.
This commit is contained in:
1 parent
6fe1b22524
commit
e140642ed0
4 files changed
+54
-14
No files matched your search
@@ -41,8 +41,9 @@
|
||||
</steps>
|
||||
|
||||
<figure>
|
||||
<title>A held capture: <gui>event held</gui> in the status bar, the axis pinned to the
|
||||
event, and the trigger marker at x = 0.</title>
|
||||
<title>A held capture</title>
|
||||
<desc><gui>event held</gui> in the status bar, the axis pinned to the event, and the
|
||||
trigger marker at x = 0.</desc>
|
||||
<media type="image" mime="image/png" src="figures/trigger-capture.png" width="1280" height="800">
|
||||
<p>The pre-trigger share is drawn to the left of the marker.</p>
|
||||
</media>
|
||||
|
||||
Reference in new issue
Block a user