docs: help pages for the time window, navigation, pause and trigger

src/help/05-window.txt

@@ -0,0 +1,30 @@
+<b>Time window</b>
+
+The window is how much time the plot shows. Every row shares one window: the figure has a
+single x link group, so the rows cannot drift apart. The trigger's event span follows it, and
+the pre-trigger share is a share of <i>this</i> window.
+
+<b>How to reach it</b>
+
+The header bar's window button opens a popover: type a number, pick a unit under it, or step a
+decade with the arrows. The button's own label is a reading of the current window in a natural
+unit, width-locked so a change of window cannot widen the header bar.
+
+<b>Worth knowing</b>
+
+• A window too long to store at the wire rate is <i>decimated, not refused</i>. The shared clock
+  takes a power-of-two stride, and each group of samples is <b>averaged</b> rather than strided,
+  so a tone above the stored Nyquist is attenuated instead of aliasing to a false low frequency.
+• The stamp stored for a group is the group's <i>mean</i>, which is where the averaging puts the
+  value. Stamping at the end of a group would shift every trace half a stored sample late.
+• Moving the window across a decimation boundary rebuilds the buffer and drops the history.
+  Walking it inside one decade is free.
+• The trigger sees the <i>stored</i> (filtered) signal, not the wire signal, because an edge
+  found on a sample that is not in the buffer could not be cut out of it.
+
+<b>Example</b>
+
+1 MS/s with 200 MB of buffer. A 2 s window stores every sample (<tt>time x1</tt>). Widen it to
+600 s and the stride becomes <tt>x16</tt>: 625 S/s stored, anti-aliased at 312.5 Hz. A 2 kHz
+sine seen through that window reads <tt>y=[-0.059, 0.079]</tt> — attenuated to about 6%, not
+folded down to a full-amplitude 125 Hz one.

src/help/06-navigate.txt

@@ -0,0 +1,34 @@
+<b>Navigating the plot</b>
+
+The plot pans and zooms with the mouse and with the keyboard. Every gesture acts on the row the
+pointer is over, and because the rows share one time axis, an x change moves all of them.
+
+<b>How to reach it</b>
+
+<b>Wheel</b> zooms both axes · <b>Shift+wheel</b> zooms x only · <b>Ctrl+wheel</b> zooms y only.
+<b>Drag</b> pans · <b>Ctrl+drag</b> is a box zoom on x · <b>Alt+drag</b> a box zoom on y.
+<b>+</b> and <b>-</b> zoom both axes; <b>Ctrl</b> with them restricts to x, <b>Alt</b> to y.
+<b>Arrow keys</b> pan, <b>f</b> fits, <b>Escape</b> cancels a gesture in progress.
+The full table is in the shortcut overview (<tt>Ctrl+/</tt>).
+
+<b>Worth knowing</b>
+
+• The keyboard zoom's modifiers are <i>not</i> the wheel's, and that is deliberate: on common
+  layouts <tt>+</tt> <i>is</i> shift+<tt>=</tt>, so a bare zoom-in already arrives with Shift
+  set and Shift could not mean anything. Ctrl/Alt mirror the box-zoom drags instead.
+• A <i>pinned</i> view is navigable within its own data but cannot leave it. While an event is
+  held, a capture is filling, or the view is paused, a zoom <i>in</i> works normally — "not
+  outside the event" is not "not readable" — but a pan or a zoom out is clamped to the data.
+• A live view is clamped to the window you asked for, not to what the ring happens to hold.
+  That is why a buffer that has only just started filling leaves its left-hand side empty
+  instead of squeezing the window down to the first few samples.
+• Zooming hard into a held capture is exact. The renderer finds the visible samples by binary
+  search over the real timestamps, never over a nominal sample grid, so a capture whose clock
+  wandered does not drift away from its axis as you zoom.
+
+<b>Example</b>
+
+Pause a live view, then press <tt>Ctrl++</tt>: x narrows and y does not move. Press
+<tt>Alt++</tt>: y narrows and x does not. Eight doublings into a held 2 s capture, the trace
+still reaches both margins — the zoom probe reports <tt>gap_px</tt> and <tt>end_px</tt> within
+a pixel or two at every step.

src/help/07-pause.txt

@@ -0,0 +1,29 @@
+<b>Pause and play</b>
+
+Pause freezes the <i>display</i>, not the acquisition. The producer keeps filling the ring at
+full rate; the view binds an immutable snapshot of the window that was on screen, and the axis
+is pinned to it.
+
+<b>How to reach it</b>
+
+The pause button in the toolbar, or <tt>Space</tt>. Press it again to resume, which rebinds the
+live ring and puts the window back on the newest data.
+
+<b>Worth knowing</b>
+
+• Nothing is lost while paused. Because the producer never stops, resuming shows current data
+  with no hole in the history behind it.
+• The axis is pinned to the <i>snapshot's own stamps</i>, not to the window that was requested.
+  A window reaching back past the oldest retained sample yields a shorter snapshot, and the
+  pinned axis is that shorter span — so you see a narrower view rather than an empty margin.
+• A paused view is pinned exactly as a held trigger event is: zoom in freely, but a pan or a
+  zoom out is clamped to the snapshot's data.
+• Pausing is the easiest way to measure a layout or read a cursor precisely, because nothing
+  under the pointer moves between frames.
+
+<b>Example</b>
+
+Pause with a 2 s window over a ring holding 1.4 s: the frozen axis reads
+<tt>[-1.40 .. 0.00]</tt> rather than <tt>[-2.00 .. 0.00]</tt> with 0.6 s of blank. The pause
+probe reports <tt>ring_produced</tt> still growing across the pause and
+<tt>event_size</tt> non-zero exactly while paused.

src/help/08-trigger.txt

@@ -0,0 +1,35 @@
+<b>Trigger</b>
+
+The trigger watches one signal for an edge through a level and captures a window around it.
+The captured window is frozen on screen until you re-arm.
+
+<b>How to reach it</b>
+
+The trigger button in the toolbar (<tt>t</tt>) reveals the trigger panel: the signal, the level,
+the edge (rising, falling, either), the mode (Normal or Single) and the pre-trigger share.
+<b>Arm</b> starts watching; <tt>a</tt> arms and disarms from the keyboard.
+
+<b>Worth knowing</b>
+
+• Arming <i>enables</i> the signal if it was off, because a trigger on a signal nobody acquires
+  can never fire.
+• The pre-trigger share is a share of the <i>display window</i>, not of the ring. A 2 s window
+  at 50% captures 1 s before the edge and 1 s after.
+• There are four display states, and the status bar names each: <tt>armed</tt> (watching,
+  nothing drawn yet), <tt>capturing</tt> (the edge was accepted and the post window is filling
+  <i>in view</i>, with the marker at x = 0), <tt>event held</tt> (the frozen capture) and
+  <tt>disarmed</tt>. A held capture is never quietly replaced by live data.
+• The first edge after arming is only accepted once the history reaches back a full pre-trigger
+  window, so a capture may legitimately be shorter than you asked for. The axis is pinned to
+  what the capture actually got.
+• Disarming <i>during</i> a capture publishes what the capture got to, so the picture on screen
+  at that moment stays on screen. No event fired, so the event count does not move.
+• The trigger reads the <b>stored</b> signal — decimated and averaged — not the wire signal.
+  A spike narrower than one decimation group is filtered away rather than triggering on data
+  the buffer does not contain.
+
+<b>Example</b>
+
+A 1 Hz sine, level 0, rising, 2 s window at 50%, Single. The capture spans
+<tt>[-1.000 .. 1.000]</tt> with <tt>n=20001</tt> samples at 10 kS/s — the span times the real
+rate, plus one — and the marker sits at x = 0 throughout.

src/help/udpscope-help.gresource.xml

@@ -13,5 +13,9 @@
     <file>02-source.txt</file>
     <file>03-signals.txt</file>
     <file>04-layout.txt</file>
+    <file>05-window.txt</file>
+    <file>06-navigate.txt</file>
+    <file>07-pause.txt</file>
+    <file>08-trigger.txt</file>
   </gresource>
 </gresources>

src/help_window.cpp

@@ -34,6 +34,10 @@ constexpr HelpPage kPages[] = {
     {"Getting started", "Choosing a source", "/org/udpscope/help/02-source.txt"},
     {"Getting started", "Signals and calibration", "/org/udpscope/help/03-signals.txt"},
     {"Getting started", "Rows, layout and drag & drop", "/org/udpscope/help/04-layout.txt"},
+    {"Viewing", "Time window", "/org/udpscope/help/05-window.txt"},
+    {"Viewing", "Navigating the plot", "/org/udpscope/help/06-navigate.txt"},
+    {"Viewing", "Pause and play", "/org/udpscope/help/07-pause.txt"},
+    {"Viewing", "Trigger", "/org/udpscope/help/08-trigger.txt"},
 };
 constexpr int kPageCount = static_cast<int>(sizeof(kPages) / sizeof(kPages[0]));