From 395c9caec381492f262a6850d370615aabce2bcc Mon Sep 17 00:00:00 2001 From: Martino Ferrari Date: Wed, 14 Oct 2026 22:30:07 +0200 Subject: [PATCH] help: send readers to the install targets, in the alert and the manual The failure alert told people to run `cmake --install build --prefix ~/.local`; that still works, but `cmake --build build --target install-help-user` is the form that needs no prefix guessing and prints the path it wrote, so the alert names it and stays its former length. The manual gains a short "Installing this manual" section on the overview page naming both targets -- the no-root user one and the prefix-driven one for a system-wide or packaged install, which the caller wraps in sudo -- and README and the GTK invariants doc follow the alert's new command. --- README.md | 9 +++++---- docs/claude/invariants-gtk-and-chrome.md | 3 ++- help/C/org.udpscope.app/overview.page | 16 ++++++++++++++++ src/help_window.cpp | 8 ++++---- 4 files changed, 27 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index bddd5b5..4a8813a 100644 --- a/README.md +++ b/README.md @@ -2466,10 +2466,11 @@ alert says **which** thing is missing, because the two have different fixes: `he looks for the document under `$XDG_DATA_HOME/help//org.udpscope.app/` then `$XDG_DATA_DIRS/help//org.udpscope.app/`, so with the set installed the alert names the missing *viewer* (`yelp`), and without it the alert names the identifier, the expected installed path and the -install command — `cmake --install build --prefix ~/.local`, which writes -`~/.local/share/help/C/org.udpscope.app/`. Two opt-in targets install the manual *alone*, without a -whole `cmake --install`: `cmake --build build --target install-help-user` writes the same -`$XDG_DATA_HOME` (default `~/.local/share`) copy the alert describes and needs no root, while +install command — `cmake --build build --target install-help-user`, the no-root form below, which +writes the set under `$XDG_DATA_HOME` (default `~/.local/share/help/C/org.udpscope.app/`) and prints +the path it wrote. Two opt-in targets install the manual *alone*, without a +whole `cmake --install`: `install-help-user` writes that `$XDG_DATA_HOME` (default `~/.local/share`) +copy and needs no root, while `cmake --build build --target install-help` writes to the configured `CMAKE_INSTALL_PREFIX` for a packager or a system-wide user to wrap in `sudo`; both print where they wrote. A build tree has neither the installed copy nor a diff --git a/docs/claude/invariants-gtk-and-chrome.md b/docs/claude/invariants-gtk-and-chrome.md index 9514051..9fc4048 100644 --- a/docs/claude/invariants-gtk-and-chrome.md +++ b/docs/claude/invariants-gtk-and-chrome.md @@ -159,7 +159,8 @@ Part of [CLAUDE.md](../../CLAUDE.md). These are rules that cost a defect to lear `$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 --install build --prefix ~/.local`, which writes `~/.local/share/help/C//`) — and a + (`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 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. diff --git a/help/C/org.udpscope.app/overview.page b/help/C/org.udpscope.app/overview.page index 76da886..9fcd3d5 100644 --- a/help/C/org.udpscope.app/overview.page +++ b/help/C/org.udpscope.app/overview.page @@ -167,4 +167,20 @@ +
+ 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:

+ +

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.

 + +
+ diff --git a/src/help_window.cpp b/src/help_window.cpp index 625bbc5..c4b96f2 100644 --- a/src/help_window.cpp +++ b/src/help_window.cpp @@ -80,10 +80,10 @@ void on_help_launched(GObject* source, GAsyncResult* result, gpointer user) { 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 --install build --prefix ~/.local\n\n" - "which writes ~/.local/share/help/C/" UDPSCOPE_HELP_NAME "/ -- the directory " - "`help:" UDPSCOPE_HELP_NAME "` resolves to. If there is no `help:` viewer either, " - "install one as well (for example `yelp`)."; + " 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`)."; } gtk_alert_dialog_set_detail(alert, detail.c_str()); gtk_alert_dialog_show(alert, launch->parent);