From 41cd8e5f38aa3ae6e4d5c798ed9eba13bb5f410e Mon Sep 17 00:00:00 2001 From: Martino Ferrari Date: Thu, 15 Oct 2026 00:17:38 +0200 Subject: [PATCH] help: recommend the system-wide install and record the location trap A Mallard set under $XDG_DATA_HOME/help is one Yelp cannot draw the figures of: its sandbox exposes the system help directories but not the user's data directory, and each figure is a separate file the page references. The pages open without their images, and through the app's help: URI the viewer spins for ever because the failed image fetch means the page's load event never fires -- which reads as a navigation failure, not a missing resource. The alert and the manual both recommended install-help-user as the no-root route, so they led users into exactly that case. Name the system-wide install first and state the user-local caveat where the advice is given, and record the finding in the GTK traps invariant so the next figure that will not draw is not chased as a markup or a file problem. --- docs/claude/invariants-gtk-and-chrome.md | 26 +++++++++++++++++++++--- help/C/org.udpscope.app/overview.page | 18 ++++++++++------ src/help_window.cpp | 15 ++++++++------ 3 files changed, 44 insertions(+), 15 deletions(-) diff --git a/docs/claude/invariants-gtk-and-chrome.md b/docs/claude/invariants-gtk-and-chrome.md index cf3e10a..12c6c29 100644 --- a/docs/claude/invariants-gtk-and-chrome.md +++ b/docs/claude/invariants-gtk-and-chrome.md @@ -158,9 +158,9 @@ Part of [CLAUDE.md](../../CLAUDE.md). These are rules that cost a defect to lear document that was never installed, so `help_installed_path()` walks the specification's own `$XDG_DATA_HOME/help///` then `$XDG_DATA_DIRS/help///` for an `index.page` and the dialog says which one it is: with the manual there, install a viewer (for example `yelp`); with - it absent, the identifier, the expected installed path and the install command - (`cmake --build build --target install-help-user`, which installs it under the user data - directory; `install-help` is the prefix-wide form for a system or packaged install) — and a + it absent, the identifier and the install command, the **system-wide** form first + (`cmake -DCMAKE_INSTALL_PREFIX=/usr .. && sudo cmake --build build --target install-help`), the + no-root `install-help-user` second with its caveat (see the location rule below) — and a viewer as well, the second possibility the error alone cannot rule out. Reporting a missing *document* as a missing *handler* is the defect that shape avoids. @@ -181,6 +181,26 @@ Part of [CLAUDE.md](../../CLAUDE.md). These are rules that cost a defect to lear (GTK4 must be forced to the Cairo renderer, `GSK_RENDERER=cairo`, or the X11 surface reads back blank). Mallard is translatable with `itstool`, but there is no i18n set-up here: only the `C` set is authored. + + **A user-local help set is one Yelp cannot draw the figures of, so the system-wide install is + the one to recommend — and this is a *location* rule, not a markup or a file rule.** Yelp + sandboxes its WebKit subprocess, and that sandbox exposes the system help directories + (`/usr/share/help`, `/usr/local/share/help`) but not `$XDG_DATA_HOME/help`: the pages load, + their `` figures do not, because each figure is a *separate file* the page references + rather than something embedded in it. The symptoms read as anything but a location problem — + opening a page *as a file* renders it with no images, and opening it through the app's `help:` + URI leaves the viewer spinning **for ever**, the failed image fetch meaning the page's load + event never fires while the sidebar title still updates, which looks like a navigation failure + rather than a missing resource. A shipped GNOME page that carries a figure + (`/usr/share/help/C/accerciser/api_browser_plugin.page`) draws either way, which is what + isolates the cause to where the set *lives*. `make install-help` (into `/usr/local`) followed + by `yelp /usr/local/share/help/C//.page` works; the same set under + `~/.local/share/help` does not. Two genuine defects were chased and fixed before the location + was found — a `
` with no `` and a `bKGD` chunk the PNG spec forbids on an + alpha image — so do not read a figure that will not draw as a repeat of either, and do not + revert those fixes: this is why both the failure alert in `src/help_window.cpp` and the + manual's own `overview.page` name the system-wide install first and state the user-local one's + caveat beside it. - **The chooser carries the same help affordances as the window, and the tour request crosses as a value — not a global.** The source chooser runs *before* `App` exists, so a user who has not started yet is the one least able to find the help; its header bar therefore has a help `GtkMenuButton` diff --git a/help/C/org.udpscope.app/overview.page b/help/C/org.udpscope.app/overview.page index 9fcd3d5..6ea5685 100644 --- a/help/C/org.udpscope.app/overview.page +++ b/help/C/org.udpscope.app/overview.page @@ -171,15 +171,21 @@ Installing this manual

The manual is a help set the desktop viewer reads off disk, so F1 opens it only once a copy sits where help: resolves. Either of two targets installs it on its own, - without building the application, and each prints where it wrote:

+ without building the application, and each prints where it wrote. Prefer the system-wide one: + it is the copy every viewer can read, and the reason is worth knowing before you pick the + other:

-

For your own account, needing no root: - cmake --build build --target install-help-user writes it under - $XDG_DATA_HOME (default ~/.local/share).

For a system-wide or packaged install: cmake --build build --target install-help writes it under the configured - CMAKE_INSTALL_PREFIX, so point that at /usr and wrap the target in - sudo.

 + CMAKE_INSTALL_PREFIX, so point that at /usr + (cmake -DCMAKE_INSTALL_PREFIX=/usr ..) and wrap the target in + sudo. A viewer reads its figures as separate files, and its sandbox exposes the + system help directories, so this copy always shows them.

+

For your own account, needing no root: + cmake --build build --target install-help-user writes it under + $XDG_DATA_HOME (default ~/.local/share). Be aware that the same + sandbox does not expose the user's data directory: those pages open, but a viewer + such as Yelp shows them without their figures.

 diff --git a/src/help_window.cpp b/src/help_window.cpp index c4b96f2..d4dfc6d 100644 --- a/src/help_window.cpp +++ b/src/help_window.cpp @@ -77,13 +77,16 @@ void on_help_launched(GObject* source, GAsyncResult* result, gpointer user) { ", so what is missing is a viewer for the `help:` URI it is opened with: install " "one (for example `yelp`) or make it the desktop's default for that scheme."; } else { + // The system-wide install is named *first* on purpose: a set under the user's data + // directory is one a sandboxed viewer (Yelp) cannot read its figures from -- the pages + // open without their images -- so the no-root route carries that caveat rather than + // leading. The message is kept no longer than the one it replaces; do the same on edit. detail += "The manual does not look installed: nothing named \"help:" UDPSCOPE_HELP_NAME - "\" was found under $XDG_DATA_HOME/help//" UDPSCOPE_HELP_NAME "/ or " - "$XDG_DATA_DIRS/help//" UDPSCOPE_HELP_NAME "/. Install it with\n\n" - " cmake --build build --target install-help-user\n\n" - "which writes the manual where `help:" UDPSCOPE_HELP_NAME "` resolves it under " - "your data directory, and prints the path it wrote. If there is no `help:` viewer " - "either, install one as well (for example `yelp`)."; + "\" was found where `help:` resolves. Install it system-wide:\n\n" + " cmake -DCMAKE_INSTALL_PREFIX=/usr .. && sudo cmake --build build --target install-help\n\n" + "That writes where the viewer looks. The no-root `install-help-user` writes under " + "your data directory instead: a sandboxed viewer shows those pages without their " + "figures. A `help:` viewer (for example `yelp`) is needed as well."; } gtk_alert_dialog_set_detail(alert, detail.c_str()); gtk_alert_dialog_show(alert, launch->parent);