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`.
73 lines
4.0 KiB
Plaintext
73 lines
4.0 KiB
Plaintext
<page xmlns="http://projectmallard.org/1.0/"
|
|
type="topic" style="task"
|
|
id="status">
|
|
|
|
<info>
|
|
<link type="guide" xref="index#output"/>
|
|
<desc>The status bar's two tiers, the activity badge, the fixed state words, and the ⓘ
|
|
detail popover.</desc>
|
|
<credit type="author copyright">
|
|
<name>Martino Ferrari</name>
|
|
</credit>
|
|
</info>
|
|
|
|
<title>Status bar and diagnostics</title>
|
|
|
|
<p>The status bar is two tiers. The bar itself is one glance line — the state, the rate and
|
|
the window — and everything else is behind the ⓘ button at its right-hand end.</p>
|
|
|
|
<section id="reach">
|
|
<title>How to reach it</title>
|
|
<p>The bar is always visible under the plot. Click <gui>ⓘ</gui> for the detail popover.</p>
|
|
</section>
|
|
|
|
<section id="knowing">
|
|
<title>Worth knowing</title>
|
|
<list>
|
|
<item><p>The badge is one glyph in four colours: green <em>alternating</em> lit and dim
|
|
means data is arriving, and a steady colour means it is not. A badge that never blinks is
|
|
not a working badge. Of the two steady colours, <em>grey</em> is no stream at all or a
|
|
pipeline you stopped (the tooltip says which), and <em>yellow</em> is a source that
|
|
answered but has sent no configuration.</p></item>
|
|
<item><p>The state field is one word from a fixed set: <code>connecting</code>,
|
|
<code>live</code>, <code>paused</code>, <code>armed</code>, <code>capturing</code>,
|
|
<code>event held</code>, <code>disarmed</code>. Two states add one field each: in trigger
|
|
mode, how long ago the last event was; while paused, how long you have been paused.</p></item>
|
|
<item><p><code>connecting</code> means there is no <em>signal list</em> yet — either no
|
|
session or a session with no configuration behind it. Every other word claims a signal
|
|
list, so until one arrives there is nothing for them to describe: nothing can be enabled
|
|
and no data is owed.</p></item>
|
|
<item><p>The paused figure is <em>wall</em> time, not stream time — the producer never
|
|
stops while paused, so it answers "how long have I been looking at this picture".</p></item>
|
|
<item><p>Nothing on the bar may change width with the stream, because the bar sits
|
|
directly above the plot and a wider label would relayout it. That is why the rate
|
|
collapses to one figure or a range rather than listing per channel, and why an elapsed
|
|
time steps to a coarser unit instead of growing digits.</p></item>
|
|
<item><p><code>gaps</code> counts packets the receiver knows it missed. It is the number
|
|
that matters: a non-zero count means samples are absent from the buffer, not merely
|
|
late.</p></item>
|
|
<item><p><code>reconnects</code> counts sessions re-established with the source. Over
|
|
unicast a climbing count usually means a second client is taking the source's single
|
|
session.</p></item>
|
|
<item><p>The starvation notice — <em>connected, but no data is arriving</em> — is that
|
|
same situation seen from the other side: the signal list is here, so something took the
|
|
stream away. A source that has sent <em>no</em> configuration gets a different notice,
|
|
<em>trying to connect</em>, because nothing was taken away — pointing the app at a port
|
|
where nothing answers is that case, and the usual cause is a streamer that is not running
|
|
or is serving another port.</p></item>
|
|
<item><p><code>stored</code> versus <code>wire</code> in the popover is the decimation.
|
|
They differ exactly when the window is too long to store at full rate.</p></item>
|
|
</list>
|
|
</section>
|
|
|
|
<section id="example">
|
|
<title>Example</title>
|
|
<p>The bar reads <code>● live · 10 kS/s · 2 s window</code>. Behind ⓘ:
|
|
<code>Stream connected, configured / packets 717 · frames 716 · gaps 0 / 3 signals · 3
|
|
channels</code>, <code>Buffer 200.0 MB · 1677 s span · time x1 / stored 10 kS/s (wire
|
|
10 kS/s)</code>, <code>Plot 1 3 traces · 195000 samples</code>,
|
|
<code>Reconnects 0</code>.</p>
|
|
</section>
|
|
|
|
</page>
|