Help: one click opens the manual, two quick clicks the note; the manual styled

One click on Help shows the explanations of every command in one
window, the names in a sans-serif and the explanations in a serif, with
a 2em margin; Copy copies them as plain text.  Two quick clicks show
the note about the documentation site.  The closed window is not
displayed (a layout rule had shown it empty on the start screen).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

client/index.html

@@ -133,8 +133,8 @@
     </div>
     <button id="session_button" type="button"
             data-help="Who is here, and the invitation to send to others.">Session</button>
-    <button id="help" type="button" data-help="Where to read about Kokkoja. With Ctrl (Command on a Mac) held, the explanations of every command in one text.">Help</button>
-    <div id="help_popup" class="popup help_popup" hidden>Help is coming!</div>
+    <button id="help" type="button" data-help="One click shows the explanations of every command, as one text in a window. Two quick clicks show where the documentation is.">Help</button>
+    <div id="help_popup" class="popup help_popup" hidden>Documentation website coming soon!</div>
     </div>
   </header>
   <div id="notice" class="notice" hidden></div>
@@ -184,7 +184,7 @@
             data-help="Copy this text.">Copy</button>
     <button id="manual_close" type="button" aria-label="Close">×</button>
   </header>
-  <pre id="manual_text" class="manual_text" tabindex="0" autofocus></pre>
+  <div id="manual_text" class="manual_text" tabindex="0" autofocus></div>
 </dialog>
 
 <dialog id="notebook_chooser" class="chooser">

client/js/main.js

@@ -40,7 +40,7 @@ import { TextEditor } from './text_editor.js';
 import { enableTooltips } from './tooltip.js';
 import { guardSelection, inField } from './selection_guard.js';
 import { QUIET_ZONE, qrModules, qrPath } from './qr_code.js';
-import { manualText } from './manual.js';
+import { manualList, manualText } from './manual.js';
 
 /**
  * The colours in the toolbar: black, red, green, blue, white (Andy's
@@ -1461,29 +1461,50 @@ async function enterSession(invitationText, name, notebook) {
   // The host's Fit and Normal scale ("A4" until 2026-10-14) reach everyone (Andy, 2026-10-08); a guest's
   // are the guest's own.
   // The page and view commands live in the Page menu (Andy, 2026-10-14:
-  // seldom used, and the one row is precious); Help is a note for now.
+  // seldom used, and the one row is precious).
   attachPopup(element('page_menu_button'), element('page_menu'));
-  // Ctrl-click (Command on a Mac) on Help: the tooltips of every command,
-  // gathered as one text (Andy, 2026-10-14).  Registered before the
-  // popup's handler, which it then stops.
+  // Help (Andy, 2026-10-15): one click shows the manual, the tooltips of
+  // every command gathered into one window (Ctrl-click until then); two
+  // clicks within DOUBLE_TAP_MS show the note about the documentation
+  // site.  Since one click opens a modal window, it must wait the
+  // interval out to be told from the first of two; the shape button's
+  // double click needs no such wait, its single click having chosen the
+  // tool already.  Two clicks are counted here rather than by the
+  // browser's dblclick, which a pen or a touch screen does not always
+  // send.
   const manualDialog = /** @type {HTMLDialogElement} */ (element('manual_dialog'));
-  element('help').addEventListener('click', (event) => {
-    if (!(event.ctrlKey || event.metaKey)) return;
-    event.stopImmediatePropagation();
-    element('manual_text').textContent = manualText(document);
+  const helpNote = attachPopup(element('help'), element('help_popup'), undefined, false);
+  const showManual = () => {
+    helpNote.close();
+    const body = element('manual_text');
+    body.replaceChildren(manualList(document));
     manualDialog.showModal();
+    body.focus();
+  };
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let helpClick = null;
+  element('help').addEventListener('click', () => {
+    if (helpClick !== null) {
+      clearTimeout(helpClick);
+      helpClick = null;
+      helpNote.open();
+    } else {
+      helpClick = setTimeout(() => {
+        helpClick = null;
+        showManual();
+      }, DOUBLE_TAP_MS);
+    }
   });
   element('manual_close').addEventListener('click', () => manualDialog.close());
   element('copy_manual').addEventListener('click', async () => {
     try {
-      await navigator.clipboard.writeText(element('manual_text').textContent ?? '');
+      await navigator.clipboard.writeText(manualText(document));
       element('copy_manual').textContent = 'Copied';
       setTimeout(() => { element('copy_manual').textContent = 'Copy'; }, 1500);
     } catch (error) {
       log(`The manual could not be copied: ${error}`);
     }
   });
-  attachPopup(element('help'), element('help_popup'));
   element('zoom_fit').addEventListener('click', () => {
     renderer.fit();
     session.sendViewCommand('fit');
@@ -1693,6 +1714,7 @@ async function enterSession(invitationText, name, notebook) {
   // For looking at the session from the browser's console during development.
   Object.assign(window, { kokkoja: {
     session, renderer, writer, loadImage, textEditor, logText,
+    manualText: () => manualText(document),
     notebook: { listNotebooks, listKeptPages, readPage, readCurrentPage, notebooksInBrowser, discardNotebook, discardPage },
   } });
 }

client/js/manual.js

@@ -4,9 +4,12 @@
  * (`data-help`), gathered from the page and written as plain text under
  * the title "User interface actions": the controls in alphabetical
  * order, each one's name on a line, its explanation on the next lines,
- * wrapped at WIDTH columns, and a blank line after (Andy, 2026-10-14:
- * Ctrl-click on Help shows it; a first form as Klammertext was replaced
- * by this the same day).
+ * wrapped at WIDTH columns, and a blank line after (Andy, 2026-10-14; a
+ * first form as Klammertext was replaced by this the same day); and the
+ * same entries as elements for the Help window (`manualList`), which
+ * the stylesheet sets, the names in a sans-serif and the explanations in
+ * a serif (Andy, 2026-10-15: one click on Help shows it, Ctrl-click
+ * until then).  The Copy button copies the text.
  */
 
 export const TITLE = 'User interface actions';
@@ -137,3 +140,27 @@ export function manualText(doc) {
   const blocks = manualEntries(doc).map(([name, help]) => `${name}\n${wrap(help, WIDTH)}\n`);
   return `${TITLE}\n\n${blocks.join('\n')}`;
 }
+
+/**
+ * The manual as elements: the title as a heading, then a description
+ * list, each control's name a term and its explanation the description.
+ * @param {Document | Element} doc
+ * @returns {DocumentFragment}
+ */
+export function manualList(doc) {
+  const owner = doc instanceof Document ? doc : doc.ownerDocument;
+  const fragment = owner.createDocumentFragment();
+  const title = owner.createElement('h3');
+  title.textContent = TITLE;
+  fragment.append(title);
+  const list = owner.createElement('dl');
+  for (const [name, help] of manualEntries(doc)) {
+    const term = owner.createElement('dt');
+    term.textContent = name;
+    const description = owner.createElement('dd');
+    description.textContent = help;
+    list.append(term, description);
+  }
+  fragment.append(list);
+  return fragment;
+}

client/kokkoja.css

@@ -257,21 +257,43 @@ h2 {
 
 .help_popup { padding: 0.8rem 1rem; }
 
-/* The generated manual (Ctrl-click on Help): the tooltips as Klammertext.
-   Its Copy button has a button's ordinary shape, not the close mark's
-   2rem; the text takes the focus when the window opens, so that the
-   keyboard scrolls it and no button's tooltip opens by itself. */
+/* The manual (one click on Help): every control's tooltip, the names in
+   the interface's sans-serif and the explanations in a serif, a 2em
+   margin on all sides of the window (Andy, 2026-10-15); as tall as its
+   contents up to most of the window, the list then scrolling.  Its Copy
+   button has a button's ordinary shape, not the close mark's 2rem; the
+   list takes the focus when the window opens, so that the keyboard
+   scrolls it and no button's tooltip opens by itself.  (`.chooser`'s own
+   box comes later in this file, hence the two classes.)  The flex layout
+   is set ONLY WHILE OPEN: on the dialog itself it would override the
+   browser's `display: none` for a closed dialog, and the empty window
+   stood at the end of the page (Andy saw it on the start screen,
+   2026-10-15; in a session it lay below the desk, out of view). */
+.chooser.manual[open] { display: flex; }
+.chooser.manual {
+  flex-direction: column;
+  width: min(46rem, 90vw);
+  height: fit-content;
+  max-height: 85vh;
+  padding: 2em;
+}
 .manual header h2 { flex: 1; min-width: 0; }
 .chooser header button.action { width: auto; padding: 0.35rem 0.8rem; margin-right: 0.5rem; font-size: inherit; line-height: normal; }
-.manual_text:focus { outline: 2px solid var(--line); outline-offset: 2px; }
+/* The focus ring only when the keyboard put the focus there (Enter on
+   Help); after a click it would frame the list for no reason. */
+.manual_text:focus-visible { outline: 2px solid var(--line); outline-offset: 2px; }
 .manual_text {
-  margin: 0;
-  max-height: 70vh;
+  flex: 1;
+  min-height: 0;
+  margin-top: 1em;
   overflow: auto;
-  white-space: pre-wrap;
-  font-size: 0.85rem;
   line-height: 1.4;
 }
+.manual_text h3 { margin: 0 0 1em; font-size: 1.1rem; }
+.manual_text dl { margin: 0; }
+.manual_text dt { font-family: system-ui, sans-serif; font-weight: 600; }
+.manual_text dd { margin: 0.15em 0 1em; font-family: serif; font-size: 1.05rem; }
+.manual_text dd:last-child { margin-bottom: 0; }
 
 .palette .swatch { width: 1.5rem; height: 1.5rem; }
 /* A colour already in the toolbar leaves its place in the grid empty. */