feat: the manual is a Mallard set opened in Yelp, not a GResource in the binary
The help was 14 Pango-markup `.txt` bodies in a second GResource, drawn into a paged `GtkWindow` built in `help_window.cpp`. That made F1 a viewer of ours with no search index, no cross-references and no translation, and it kept the manual in the *binary* when every other desktop application's is a document on disk. It is now a real Mallard set: help/C/org.udpscope.app/ index.page + 14 topic pages + figures/*.png and `show_help()` hands `help:org.udpscope.app` to whatever the desktop registered for the `help:` scheme -- Yelp on GNOME -- through a `GtkUriLauncher`, reporting a launch failure with a `GtkAlertDialog` rather than a click that silently does nothing. The paged window's builder, the page table and `help_self_check()`'s markup validation are gone with the resource. The document identifier is the desktop file's own basename (its desktop-file id), derived in CMakeLists from `data/org.udpscope.app.desktop.in`, so the same string is the `.desktop` name, the GApplication id and the install directory at once. The set is installed by a new `install()` rule to `<datadir>/help/C/org.udpscope.app/` -- where the freedesktop Help System Specification's `help:` URI resolves `help:<id>` -- so the manual is read from a datadir by another process even though the binary has no install step. `UDPSCOPE_HELP_NAME` and `UDPSCOPE_HELP_DIR` are compiled in from that one place. The 14 pages were migrated fact for fact, but restructured the Mallard way: a `<desc>` per page (what a search result shows), `<steps>` for procedures, `<terms>` for option lists, `<gui>`/`<key>`/`<keyseq>` for interface words and keys, `<note>` for the asides, and a topic graph via `<link type="guide" xref="index#main"/>`. The figures are annotated screenshots produced by `tools/make-help-shots.sh`, which drives the app headlessly against `tools/mock_udpstreamer.py` and draws the boxes with ImageMagick; the side panel's box is measured from the app's own `side=NNNx` dump reading, the header and status bands come from a documented table, and a crop whose standard deviation is 0 fails the script. `cmake --build build --target test-help` checks the set the way `test-ui` checks the `.ui` files: `yelp-check`'s offline subcommands (links, media, orphans, ids) and a `yelp-build html` render. `yelp-check validate` is deliberately absent -- it fetches the Mallard RelaxNG schema over the network and fails offline for that reason, not for a fault in the pages. The `[help]` probe reading changes with the resource it was written for. `parsed == pages` over in-binary markup cannot exist now, so `help_self_check()` scans `UDPSCOPE_HELP_DIR` and the line reads `topics=14 index=1 figures=3`; `topics=0 index=0` is the manual missing from the tree, which is the finding the old count named. Verified: clean build with the documented three warnings (the help bundle's `-Woverlength-strings` is gone, so the baseline moves from four to three); test-ui 14/14; test-help clean (the four subcommands and 15 pages rendered); a temp-prefix install lands 15 `.page` files and 3 figures at `share/help/C/org.udpscope.app/`; the headless run reads `[help] topics=14 index=1 figures=3 dir=...` with 0 Gtk-CRITICAL. Yelp's own window could not be exercised on this box -- it starts under Xvfb, activates its portals and never maps, the same WebKit/portal limitation that stops a grab -- so its rendering and its search index are unverified here; the content pipeline was (`yelp-build` renders the whole set). Docs: the manual's build/install/open story in `build-and-run.md` and README; the warning baseline in `verification.md`/CLAUDE.md; the help bullets in `invariants-gtk-and-chrome.md`; the `[help]` line in `probe-readings.md`.
This commit is contained in:
1 parent
620473a5be
commit
c1460a6977
47 files changed
+1910
-1056
No files matched your search
@@ -0,0 +1,70 @@
|
||||
<page xmlns="http://projectmallard.org/1.0/"
|
||||
type="topic" style="task"
|
||||
id="signals">
|
||||
|
||||
<info>
|
||||
<link type="guide" xref="index#main"/>
|
||||
<link type="seealso" xref="layout"/>
|
||||
<desc>How the source's CONFIG becomes channels, what enabling a signal starts, and how a
|
||||
signal's scale and offset are calibrated.</desc>
|
||||
<credit type="author copyright">
|
||||
<name>Martino Ferrari</name>
|
||||
</credit>
|
||||
</info>
|
||||
|
||||
<title>Signals and calibration</title>
|
||||
|
||||
<p>The source's CONFIG message describes its signals: a name, a unit and a type. udpscope
|
||||
turns each enabled signal into a <em>channel</em> — a ring of values beside the shared time
|
||||
ring — and a channel is what a trace plots. Calibration is a scale and an offset applied at
|
||||
ingest.</p>
|
||||
|
||||
<section id="reach">
|
||||
<title>How to reach it</title>
|
||||
<steps>
|
||||
<item>
|
||||
<p>Open the side panel (<key>s</key>), which lists every signal with a switch.</p>
|
||||
</item>
|
||||
<item>
|
||||
<p>The <gui>Signal list</gui> item in the overflow menu opens the editor where the
|
||||
unit and the calibration live.</p>
|
||||
</item>
|
||||
</steps>
|
||||
</section>
|
||||
|
||||
<section id="knowing">
|
||||
<title>Worth knowing</title>
|
||||
<list>
|
||||
<item><p>Signals start disabled, and enabling one is what starts acquiring it. A trigger
|
||||
on a signal nobody acquires can never fire, so arming a trigger enables its signal for
|
||||
you.</p></item>
|
||||
<item><p><gui>Calibrate</gui> in a signal's row menu opens the gain and offset it is
|
||||
<em>currently</em> drawn through, so a trace already scaled by a gain of 2 shows 2 —
|
||||
pressing <gui>Apply</gui> confirms it rather than resetting it. A signal nobody
|
||||
calibrated shows the identity, 1 and 0.</p></item>
|
||||
<item><p>Calibration is applied <em>at ingest</em>, so changing it re-plans the buffer
|
||||
and drops the history. So does enabling or disabling a signal, and so does a new
|
||||
CONFIG. An empty plot for a second after one of those is the ring refilling, not a
|
||||
fault.</p></item>
|
||||
<item><p>The stream's first signal is usually its <em>timestamp</em>, and that one is
|
||||
never acquired. It cannot be plotted, measured or used as a math source, and udpscope
|
||||
refuses to put it in a row rather than binding a trace that would read nothing for
|
||||
ever.</p></item>
|
||||
<item><p>A signal's colour follows the <em>signal</em>, not the slot, so the same signal
|
||||
on two rows is one colour and the side panel's chip identifies it unambiguously. A
|
||||
signal on no row gets a grey chip rather than none, so the panel's rows keep their
|
||||
height.</p></item>
|
||||
<item><p><em>Click a coloured chip to change that signal's colour.</em> A grey chip
|
||||
names no trace, so it is not clickable. The colour is saved with the session;
|
||||
<gui>Default colour</gui> in the signal's ⋯ menu gives the palette entry back.</p></item>
|
||||
</list>
|
||||
</section>
|
||||
|
||||
<section id="example">
|
||||
<title>Example</title>
|
||||
<p>A source declaring <code>time</code>, <code>sine</code>, <code>ramp</code> and
|
||||
<code>noise</code> yields three plottable signals. Enable all three and the exit dump
|
||||
reads <code>3 signals, 3 channels</code>; <code>time</code> is not among them.</p>
|
||||
</section>
|
||||
|
||||
</page>
|
||||
Reference in new issue
Block a user