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:
Martino Ferrari committed 2026-10-14 17:15:31 +02:00
1 parent 6fe1b22524
commit e140642ed0
4 files changed
+54 -14

No files matched your search

+3 -2
View File
@@ -89,8 +89,9 @@
are rebuilt whenever it changes.</p>
<figure>
<title>The math channel editor: nodes as boxes on a canvas, the orange dot marking the
output, and the selected node's parameters beside it.</title>
<title>The math channel editor</title>
<desc>Nodes as boxes on a canvas, the orange dot marking the output, and the selected
node's parameters beside it.</desc>
<media type="image" mime="image/png" src="figures/math-editor.png" width="938" height="420">
<p>A sine source wired through a gain into a filter, with the output on the last
node.</p>
+6 -5
View File
@@ -33,8 +33,9 @@
is still there when you need it — an export writes it as a second column.</p>
<figure>
<title>The udpscope window on a live source: the header bar above the plots, the side
panel on the right, and the status bar along the bottom.</title>
<title>The udpscope window</title>
<desc>The header bar above the plots, the side panel on the right, and the status bar
along the bottom.</desc>
<media type="image" mime="image/png" src="figures/main-window.png" width="1280" height="800">
<p>One figure of three rows with four signals enabled, the Measure tab open in the
side panel, and the status bar reading <gui>live</gui>.</p>
@@ -95,9 +96,9 @@
</terms>
<figure>
<title>A held capture: the trigger has latched, the state reads
<gui>event held</gui>, and the axis is pinned to the event rather than to the live
edge.</title>
<title>A held capture</title>
<desc>The trigger has latched, the state reads <gui>event held</gui>, and the axis is
pinned to the event rather than to the live edge.</desc>
<media type="image" mime="image/png" src="figures/trigger-capture.png" width="1280" height="800">
<p>The trigger marker sits at x = 0 and the pre-trigger share of the window is drawn
to its left.</p>
+3 -2
View File
@@ -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>