working on todo.md features

src/help/13-sessions.txt

@@ -1,34 +1,60 @@
 <b>Sessions and settings</b>
 
-udpscope stores one session file per source, so reopening a source gives you the scope you
-closed. There is no global preferences file: the session <i>is</i> the settings.
+udpscope stores named sessions — <i>configurations</i> — per source, so reopening a source gives
+you the scope you closed, and one source can hold several arrangements for different experiments.
+There is no global preferences file: the session <i>is</i> the settings.
 
 <b>How to reach it</b>
 
 Nothing to open — the file is written as you work. Its path is in the About dialog, and the
 directory is <tt>$XDG_CONFIG_HOME/udpscope</tt>, or <tt>~/.config/udpscope</tt> when that is
-unset. Each file is named <tt>&lt;host&gt;_&lt;port&gt;.toml</tt>.
+unset. Each source has a directory <tt>&lt;host&gt;_&lt;port&gt;/</tt> holding one
+<tt>&lt;name&gt;.toml</tt> per configuration and an <tt>active</tt> file naming the one it is on.
+
+<b>Configurations</b>
+
+<b>Configurations…</b> in the menu lists the running source's configurations: click a row to open
+it, <tt>×</tt> to delete it, or type a name and a note and press <i>Save this session</i> to keep
+the current arrangement under a new one. Opening a configuration saves the current session first,
+so switching never loses what it switches from.
+
+The startup chooser (start with no <tt>--server</tt>) lists one row per configuration, with its
+note and its settings, so two arrangements of one source are told apart before they open.
+
+A configuration also carries the settings that can only be decided when the buffers are
+allocated: the <b>buffer size</b> (<tt>--buffer-mb</tt>), relative time, and the packet capture's
+ring size. Opening a configuration from the chooser applies all three; switching inside a running
+app applies the rest and says in the status line that these take effect on the next start.
+
+The chooser's form sets the first two for a new host, and its pencil button edits them on an
+existing configuration — along with the name and the note. Renaming a configuration, or editing
+the address it points at, moves it: the old file is removed rather than left behind.
 
 <b>Worth knowing</b>
 
-• What a session persists: the time window, the rows and each row's slot signals, the
-  calibration, which signals are enabled, the math channels with their graphs, and the
-  measurements pane.
+• What a configuration persists: the time window, the rows and each row's slot signals, the
+  calibration, the trace colours, which signals are enabled, the math channels with their graphs,
+  the measurements pane — and the startup settings: buffer size, relative time and the packet
+  capture's ring size.
 • Signal identity is the <i>name</i> throughout, because a new CONFIG renumbers the channels.
 • A file written by a run against a source whose streamer was down would name no signals at all,
   so such a run does <b>not</b> write: a configured session is never overwritten by a run that
-  configured nothing.
+  configured nothing. (The chooser hides such a file for the same reason.)
 • The multicast group and the interface live <i>inside</i> the file, because its name cannot
   carry them. A file from an older build has neither key and loads as unicast on the default
   route.
-• The startup chooser lists only files that name at least one signal, which is what keeps it the
-  sources you configured rather than every port you have ever tested against.
-• Deleting a file is a supported way to start a source over; the chooser's <tt>×</tt> does
-  exactly that.
+• The chooser lists only configurations that name at least one signal, which is what keeps it the
+  sessions you configured rather than every port you have ever tested against.
+• Deleting a configuration is a supported way to start over; the chooser's <tt>×</tt> and the
+  dialog's do exactly that.
+• A session from before configurations existed is imported once as the configuration
+  <tt>default</tt>, and the old file is kept beside the directory as
+  <tt>&lt;host&gt;_&lt;port&gt;.toml.imported</tt>.
 
 <b>Example</b>
 
-Connect to <tt>127.0.0.1:8000</tt>, drop three signals on row 1 and set a 2 s window.
-<tt>~/.config/udpscope/127.0.0.1_8000.toml</tt> now holds <tt>rows=1 window_s=2</tt> with
-<tt>signals = ["sine", "ramp", "noise", ""]</tt>, and the next run reports
-<tt>layout loaded from …/127.0.0.1_8000.toml</tt> with those signals already acquired.
+Connect to <tt>127.0.0.1:8000</tt>, drop three signals on row 1, set a 2 s window, and save the
+session as <tt>bench</tt> with a note. <tt>~/.config/udpscope/127.0.0.1_8000/bench.toml</tt> now
+holds <tt>window_s=2 comment="…"</tt> with <tt>signals = ["sine", "ramp", "noise", ""]</tt>, and
+the next run reports <tt>layout loaded from …/127.0.0.1_8000/bench.toml</tt> with those signals
+already acquired.