improving doc

src/help/01-overview.txt

@@ -1,26 +1,72 @@
 <b>What udpscope is</b>
 
-udpscope plots a live UDPStreamer source. One window holds up to 8 rows of plots, each
-with up to 4 traces; every row shares one time axis, so the whole figure scrolls together.
-Acquisition runs on its own thread and writes a ring buffer sized from --buffer-mb; the
-drawing thread reads whatever that ring holds when a frame starts.
+udpscope plots a live UDPStreamer source. One window holds up to 8 rows of plots, each with up
+to 4 traces, and every row shares one time axis, so the whole figure scrolls together.
+Acquisition runs on its own thread and writes a ring buffer sized from <tt>--buffer-mb</tt>;
+the drawing thread reads whatever that ring holds when a frame starts, which is why a trace
+never makes the window stutter.
+
+The stream is the clock. Every time you read on screen is a timestamp the source sent, never
+your machine's, so a stalled source freezes the view instead of scrolling it -- and a source
+whose clock steps still gets the window you asked for.
 
 <b>How to reach it</b>
 
-Start the app with a source (<tt>udpscope --server 127.0.0.1 --port 8000</tt>), or start it
-with no <tt>--server</tt> and pick one from the chooser. The signals arrive disabled; turn
-one on in the side panel (<tt>s</tt>) and drag it onto a row.
+Start the app with a source (<tt>udpscope --server 127.0.0.1 --port 8000</tt>), or start it with
+no <tt>--server</tt> and pick one from the chooser, which lists the sessions you have opened
+before. A unicast source serves one client at a time: if a second viewer connects, they take
+turns and the status bar says so. To watch one source from several instances, use
+<tt>--multicast</tt> with the group and <tt>--interface</tt> with the local address.
+
+The signals arrive <i>disabled</i>. Nothing is acquired until you turn one on in the signal
+list, and enabling is what starts acquisition -- so a freshly opened scope with an idle side
+panel is working correctly, not failing to connect.
+
+<b>The window</b>
+
+• <b>The header bar</b> -- left to right: the time window (<tt>2 s</tt>), the trigger and the
+  pause, then the pane switches -- signal list, cursors, measurements, math, side panel -- and
+  the menu, which holds Fit to data, the layout editor, Export, Keyboard shortcuts, Help and
+  About.
+
+• <b>The side panel</b> -- the trigger, cursors, measurements and math panes at the top, then
+  the signal list: one row per signal with its colour, an enable switch, its name and its unit.
+  Signals are dragged from here onto a plot row.
+
+• <b>The plot</b> -- up to 8 rows, each with its own y axis and up to 4 traces, all on one
+  shared time axis. Right-click a row for its own menu (fit, add a signal, remove a trace).
+
+• <b>The status bar</b>, directly above the plot's bottom edge -- the state word, the stored
+  sample rate and the window, and the ⓘ beside it for packets, gaps and the buffer's own
+  figures. The second screenshot above is what a held capture looks like: <tt>event held</tt>,
+  the axis pinned to the event, and the trigger marker at the edge.
+
+<b>The first five minutes</b>
+
+1. <b>Connect.</b> With no <tt>--server</tt>, pick a stored session or type a host and port.
+2. <b>Enable a signal</b> in the signal list. The plot stays empty for the first fraction of a
+   second while the first window fills -- the buffer holds only what has arrived.
+3. <b>Drag it onto a row.</b> Drop a second signal on another row, or the same signal again for
+   a second view of it. The colour is per signal, so it is the same one wherever it appears.
+4. <b>Set the window</b> with the control in the header bar: type a number, pick a unit, or step
+   a decade. The trigger's event window is a share of this span, so a window change moves it.
+5. <b>Pause</b> (<tt>space</tt>) to look at a still picture; the producer keeps filling the
+   buffer behind it, and resuming shows what arrived meanwhile rather than a hole.
+6. <b>Arm the trigger</b> (<tt>a</tt>) and wait for a latch: the view freezes on one event, and
+   you can zoom in on it. Disarming mid-capture keeps what the capture got.
+7. <b>Measure it</b> -- the measurements pane computes a statistic of the visible window, and
+   <b>show on plot</b> marks it as a ruler or a pair of markers.
+8. <b>Save the data</b> with Export visible range, which writes the plotted signals over the
+   window at the stored rate to <tt>.npy</tt> or <tt>.csv</tt>.
 
 <b>Worth knowing</b>
 
-• Nothing is acquired until a signal is enabled. Enabling is what starts acquisition, so a
-  freshly opened scope with an idle side panel is working correctly.
-• The stream carries its own clock. Every time on screen is a stream timestamp, never the
-  local wall clock, which is why a stalled source freezes the view instead of scrolling it.
-• The window remembers itself. Rows, traces, the time window, calibration, math channels
-  and measurements are written to a session file per host and port, and reloaded next time.
-
-<b>Example</b>
-
-A 3-signal source at 10 kS/s with a 200 MB buffer holds 1677 s of history. Enable all three,
-drop them on row 1, and the status bar reads <tt>● live · 10 kS/s · 2 s window</tt>.
+• A signal nobody enables costs nothing -- no buffer, no socket work, no measurements.
+• The window remembers itself. Rows, traces, the time window, calibration, which signals were
+  enabled, the math channels with their graphs, and the measurements are written per host and
+  port, and reloaded the next time you open that source.
+• A very wide window on a fast stream is drawn from averaged groups of samples, so the rate in
+  the status bar falls: that is the anti-alias filter, not a fault -- striding would fold a fast
+  signal back as a slow one, which looks entirely plausible on screen.
+• Every instrument the app computed -- the trigger marker, the measurement marks -- is locked to
+  the pointer's reach. The cursors are yours to drag; those are not.

src/help/11-math.txt

@@ -33,3 +33,19 @@ orange dot marks the output node.
 same source passes 50 Hz at 0.97 and 2 kHz at 0.002; a 1 kHz band pass with Q=2 passes 200 Hz at
 0.05, 1 kHz at 0.95 and 4 kHz at 0.05. Each derived channel must hold exactly as many samples as
 the shared clock has time slots.
+
+<b>Why an operation sometimes does nothing</b>. A graph's <i>output</i> is the node whose value
+becomes the channel, and it is drawn as the orange dot. A new graph is built source, then operation,
+and the last node added becomes the output -- but a graph whose output is left on the source is
+valid and simply passes its input through, which is the usual reason a gain or a filter appears to
+have no effect. <i>Set as output</i> moves the dot.
+
+<b>Save refuses an incomplete graph</b>, and says why: an input that is not connected, no output
+chosen, or a <i>channel</i> node naming a signal the scope is not acquiring. Only the channels being
+acquired are offered, because a source that is not acquired reads as no data for ever -- and a graph
+that reads NaN is harder to diagnose than one that would not save.
+
+<b>The filters are real filters.</b> A math channel's samples are produced as the stream arrives,
+once per stored slot, so a low pass carries the history a filter needs. A cutoff typed in hertz is
+against the <i>stored</i> rate, which is the wire rate until a wide window makes the buffer decimate
+-- the status line's rate is that number, and the filters are rebuilt whenever it changes.

src/help/udpscope-help.gresource.xml

@@ -23,5 +23,12 @@
     <file>12-export.txt</file>
     <file>13-sessions.txt</file>
     <file>14-status.txt</file>
+  
+    <!-- The screenshots live with the user documentation (docs/); the resource aliases
+         them under `img/` so a help page can name one by resource path. The path is relative
+         to this manifest's directory. -->
+    <file alias="img/main-window.png">../../docs/img/main-window.png</file>
+    <file alias="img/trigger-capture.png">../../docs/img/trigger-capture.png</file>
+    <file alias="img/math-editor.png">../../docs/img/math-editor.png</file>
   </gresource>
 </gresources>