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.
This commit is contained in:
Martino Ferrari committed 2026-10-15 00:17:38 +02:00
1 parent 6138e6bdce
commit 41cd8e5f38
3 files changed
+44 -15

No files matched your search

+9 -6
View File
@@ -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/<lang>/" UDPSCOPE_HELP_NAME "/ or "
"$XDG_DATA_DIRS/help/<lang>/" 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);