Martino Ferrari
c1460a6977
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`.
88 lines
4.5 KiB
Plaintext
88 lines
4.5 KiB
Plaintext
<page xmlns="http://projectmallard.org/1.0/"
|
|
type="topic" style="task"
|
|
id="cursors">
|
|
|
|
<info>
|
|
<link type="guide" xref="index#analysis"/>
|
|
<link type="seealso" xref="measurements"/>
|
|
<desc>The shared vertical cursor pair and the per-row horizontal rulers, their four modes,
|
|
and how a reading is formatted.</desc>
|
|
<credit type="author copyright">
|
|
<name>Martino Ferrari</name>
|
|
</credit>
|
|
</info>
|
|
|
|
<title>Cursors</title>
|
|
|
|
<p>Cursors read values off the traces. There are two kinds: one <em>shared vertical
|
|
pair</em> that every row carries at the same time, and <em>horizontal rulers</em>, one pair
|
|
per row, that belong to that row alone.</p>
|
|
|
|
<section id="reach">
|
|
<title>How to reach it</title>
|
|
<steps>
|
|
<item>
|
|
<p>Press the cursors button in the toolbar, or <key>c</key>.</p>
|
|
</item>
|
|
<item>
|
|
<p>The pane below the plot shows the readings and owns a <gui>Reset</gui> button.
|
|
Drag a marker to move it.</p>
|
|
</item>
|
|
<item>
|
|
<p>The mode dropdown offers four modes: <gui>vertical</gui> (the shared time pair),
|
|
<gui>horizontal</gui> (the per-row rulers), <gui>both</gui>, and <gui>mix</gui>.</p>
|
|
</item>
|
|
</steps>
|
|
</section>
|
|
|
|
<section id="knowing">
|
|
<title>Worth knowing</title>
|
|
<list>
|
|
<item><p>The vertical pair is <em>one</em> time for the whole figure, so moving it on
|
|
any row moves it on all of them. That is what makes <code>dt</code> meaningful across
|
|
rows.</p></item>
|
|
<item><p>A ruler belongs to its row and nothing shares it, so two rows' rulers are
|
|
independent.</p></item>
|
|
<item><p><gui>mix</gui> is the reading mode: one line per <em>bound</em> trace, with the
|
|
trace's own values at each marker and their difference. A slot with a name but no
|
|
channel behind it is not a trace and gets no line.</p></item>
|
|
<item><p>A value is the <em>nearest stored sample's</em>, never a number between two
|
|
samples. Zoom in past the sample spacing and the line between two samples is something
|
|
the plot drew, not data — so a reading off it would be the drawing. The hover crosshair
|
|
reads the same way.</p></item>
|
|
<item><p>Every reading carries a <em>metric prefix</em> so the digits sit in
|
|
<code>1..999</code>: <code>10.52 mV</code>, not <code>0.01 V</code>. Two decimals is all
|
|
an instrument landing on an <code>f32</code> sample can claim, so without the prefix a
|
|
small value would read <code>0.00</code> and the reading would be gone. A stream that
|
|
declares no unit gets the prefix anyway, written tight against the number
|
|
(<code>585.24m</code>) — the space separates the number from its unit, and a spaced
|
|
<code>m</code> with nothing after it would read as metres.</p></item>
|
|
<item><p>A marker past the newest sample reads <code>--</code>. With only one marker
|
|
over data the row reads <code>partial</code>: a difference between a number and nothing
|
|
is not a number.</p></item>
|
|
<item><p>In <gui>mix</gui> each marker also places a crossing annotation per trace,
|
|
which is what lets you see on the plot which sample a number came from. It is <em>on
|
|
that sample</em>, so when the marker falls between two it sits a little off its own
|
|
line: the line is where you put the marker, the dot is the datum being quoted. The hover
|
|
crosshair's mark snaps the same way, and is drawn larger than a trace's sample dots so
|
|
it does not read as one more sample.</p></item>
|
|
<item><p>The time row exists only in the modes that show the vertical pair.
|
|
<gui>horizontal</gui> has no time row, by design.</p></item>
|
|
<item><p>A cursor <em>stays where you put it</em> while a live view rolls under it,
|
|
which is what a bench scope does: its <code>T0</code> is an age, so a marker left at
|
|
<code>-1.5s</code> keeps reading the sample a second and a half old as the stream
|
|
advances. A measurement's marks do the opposite — they travel with the sample they
|
|
measured — because a cursor is a question you asked and a mark is an answer about one
|
|
particular sample.</p></item>
|
|
</list>
|
|
</section>
|
|
|
|
<section id="example">
|
|
<title>Example</title>
|
|
<p>Three traces in <gui>mix</gui> mode with both markers over data: 3 lines and 6 crossing
|
|
marks, each line reading like <code>sine 0.31 V -0.84 V -1.15 V</code>. Move the second
|
|
marker past the newest sample and the third column reads <code>--</code>.</p>
|
|
</section>
|
|
|
|
</page>
|