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`.
68 lines
3.0 KiB
Plaintext
68 lines
3.0 KiB
Plaintext
<page xmlns="http://projectmallard.org/1.0/"
|
|
type="guide" style="task"
|
|
id="index">
|
|
|
|
<info>
|
|
<desc>udpscope plots a live UDPStreamer source as one figure of up to eight stacked
|
|
plot rows sharing a single time axis, with a trigger, cursors, measurements, math
|
|
channels and an export. This manual covers connecting, the window and its panels,
|
|
navigating and pausing the plot, the trigger and its event cache, analysis, and
|
|
saving and exporting.</desc>
|
|
</info>
|
|
|
|
<title>udpscope</title>
|
|
|
|
<section id="main">
|
|
<title>Getting started</title>
|
|
<list>
|
|
<item><p><link xref="overview">Overview</link> — what udpscope is, how it reaches a
|
|
source, the window and its panels, and a first five minutes.</p></item>
|
|
<item><p><link xref="source">Choosing a source</link> — the command line, the
|
|
chooser, and opening an exported waveform instead of a live stream.</p></item>
|
|
<item><p><link xref="signals">Signals and calibration</link> — how a signal becomes
|
|
a channel, what starts acquisition, and how a scale and offset are applied.</p></item>
|
|
<item><p><link xref="layout">Rows, layout and drag & drop</link> — up to eight
|
|
rows, four traces each, and the layout editor.</p></item>
|
|
</list>
|
|
</section>
|
|
|
|
<section id="viewing">
|
|
<title>Viewing</title>
|
|
<list>
|
|
<item><p><link xref="window">Time window</link> — the one control that changes the
|
|
window, and the decimation a long window causes.</p></item>
|
|
<item><p><link xref="navigate">Navigating the plot</link> — panning, zooming and
|
|
fitting with the mouse and the keyboard.</p></item>
|
|
<item><p><link xref="pause">Pause and play</link> — freezing the display without
|
|
stopping the stream, and how long you have been looking.</p></item>
|
|
<item><p><link xref="trigger">Trigger</link> — the four trigger shapes, arming,
|
|
hold-off, the event cache, and searching the buffer.</p></item>
|
|
</list>
|
|
</section>
|
|
|
|
<section id="analysis">
|
|
<title>Analysis</title>
|
|
<list>
|
|
<item><p><link xref="cursors">Cursors</link> — the shared vertical pair and the
|
|
per-row horizontal rulers.</p></item>
|
|
<item><p><link xref="measurements">Measurements</link> — a statistic of the visible
|
|
window, its on-plot marks, and its statistics line.</p></item>
|
|
<item><p><link xref="math">Math channels</link> — building a derived channel from a
|
|
graph of source nodes, operations and one output.</p></item>
|
|
</list>
|
|
</section>
|
|
|
|
<section id="output">
|
|
<title>Output and state</title>
|
|
<list>
|
|
<item><p><link xref="export">Saving and export</link> — the visible range to
|
|
<file>.npy</file>, <file>.csv</file> or <file>.mf3</file>.</p></item>
|
|
<item><p><link xref="sessions">Sessions and settings</link> — the per-source
|
|
configuration files and what they carry.</p></item>
|
|
<item><p><link xref="status">Status bar and diagnostics</link> — the glance line, the
|
|
ⓘ popover, and the activity badge.</p></item>
|
|
</list>
|
|
</section>
|
|
|
|
</page>
|