build: install the manual alone, into the prefix or the user datadir

The manual is the only thing udpscope installs, but the only way to get it
where `help:` resolves was a whole `cmake --install`. Two opt-in targets
now install just the set, each printing where it wrote:

- install-help goes through the install machinery into CMAKE_INSTALL_PREFIX
  (reachable via the new Help component), so a packager or a system-wide
  user points it at /usr and wraps it in sudo;
- install-help-user resolves the user data directory the way the app does
  ($XDG_DATA_HOME, else $HOME/.local/share) and copies there without root.

Neither is built by default and neither changes what `cmake --install`
does; the install() rule keeps its destination.

CMakeLists.txt

@@ -89,10 +89,48 @@ file(GLOB UDPSCOPE_HELP_FILES CONFIGURE_DEPENDS
 # so the set lands at `<prefix>/share/help/C/<document>/`, which is exactly where a viewer
 # looks. There is no install step for the binary itself (see the desktop-entry target below),
 # but the manual is *read from a datadir* by another process, so it has to be installable.
+#
+# `COMPONENT Help` is what lets the opt-in targets below install *only* the manual: it names this
+# rule, and `cmake --install --component Help` runs it and nothing else. The ordinary
+# `cmake --install` installs every component, so its behaviour is unchanged -- the component is a
+# filter a caller may apply, not a change to the default.
 install(DIRECTORY ${UDPSCOPE_HELP_SRC}/
         DESTINATION ${CMAKE_INSTALL_DATADIR}/help/C/${UDPSCOPE_HELP_NAME}
+        COMPONENT Help
         FILES_MATCHING PATTERN "*.page" PATTERN "*.png" PATTERN "*.jpg")
 
+# --- installing the manual alone: prefix-wide and user-local, both opt-in -----
+# A user who runs the binary out of a build tree wants *just* the manual where `help:` resolves,
+# and not the `cmake --install` of a whole project. These two targets are that, one per
+# destination; neither is built by default and neither is touched by `cmake --build build`.
+#
+# `install-help` honours `CMAKE_INSTALL_PREFIX`, so a packager or a system-wide user points it at
+# `/usr` with -DCMAKE_INSTALL_PREFIX at configure time. It goes through the install machinery
+# (`cmake --install`) rather than a hand-rolled copy, which is what makes DESTDIR and `--prefix`
+# behave exactly as they do for the ordinary install. It cannot install system-wide on its own:
+# `/usr` is root-owned, so the target writes to the configured prefix and a system-wide caller
+# wraps it in `sudo` -- a build target has no more privilege than the shell that runs it.
+add_custom_target(install-help
+  COMMAND ${CMAKE_COMMAND} --install ${CMAKE_BINARY_DIR} --component Help
+  COMMENT "Installing the manual into ${CMAKE_INSTALL_PREFIX}"
+  VERBATIM)
+
+# `install-help-user` is the no-root case the launch-failure alert names. It resolves the user
+# data directory the way `help_installed_path()` does -- `$XDG_DATA_HOME` when it is set,
+# `$HOME/.local/share` otherwise, the XDG Base Directory Specification's own default -- and copies
+# the set there. The copy is done by a script rather than by `cmake --install --prefix` because
+# the destination is the *data directory*, not a prefix: `cmake --install`'s datadir is always
+# `<prefix>/share`, so an arbitrary `$XDG_DATA_HOME` cannot be expressed as a prefix. The script
+# prints every path it wrote; the copy uses the install rule's file filter, so both destinations
+# carry the same tree.
+add_custom_target(install-help-user
+  COMMAND ${CMAKE_COMMAND}
+          -DHELP_SRC=${UDPSCOPE_HELP_SRC}
+          -DHELP_NAME=${UDPSCOPE_HELP_NAME}
+          -P ${CMAKE_CURRENT_SOURCE_DIR}/cmake/install_help_user.cmake
+  COMMENT "Installing the manual into the user's XDG data directory"
+  VERBATIM)
+
 # --- UI files: GtkBuilder XML in a GResource ----------------------------------
 # The third bundle, for the same reason as the other two: `.ui` files are data, so they are compiled
 # in rather than looked for at runtime -- and `preprocess="xml-stripblanks"` makes a malformed one a

README.md

@@ -2467,7 +2467,12 @@ looks for the document under `$XDG_DATA_HOME/help/<lang>/org.udpscope.app/` then
 `$XDG_DATA_DIRS/help/<lang>/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/`. A build tree has neither the installed copy nor a
+`~/.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
+`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
 `help:` handler, and **either is enough to make `F1` do nothing**; that is the failure this names.
 `cmake --build build --target test-help` checks the set the way `test-ui` checks the `.ui` files:
 `yelp-check`'s offline subcommands (links, media, orphans, ids) and a `yelp-build html` render;

cmake/install_help_user.cmake

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: MIT
+#
+# The `install-help-user` target's body. Copies the Mallard help set into the user's XDG data
+# directory -- where `help:<id>` resolves without root -- and prints every path it wrote.
+#
+# `$XDG_DATA_HOME` is honoured when it is set, and `$HOME/.local/share` is the fallback when it
+# is not: that is the XDG Base Directory Specification's own stated default for the variable, and
+# it is the default `help_installed_path()` falls back to as well, so the manual lands where the
+# application and the desktop viewer look for it. The variable names a *data directory*, not a
+# prefix -- its `share/` is not appended -- so the set goes to `<data_home>/help/C/<id>/`. An
+# arbitrary `$XDG_DATA_HOME` need not end in `share`, which is exactly why this copies the tree
+# rather than deferring to `cmake --install --prefix`, whose datadir is always `<prefix>/share`.
+#
+# Like the desktop-entry target, this runs only when it is named: `cmake --build build` never
+# touches the user's data directory.
+#
+# Expects -DHELP_SRC= and -DHELP_NAME= on the command line.
+
+if(DEFINED ENV{XDG_DATA_HOME} AND NOT "$ENV{XDG_DATA_HOME}" STREQUAL "")
+  set(data_home "$ENV{XDG_DATA_HOME}")
+elseif(DEFINED ENV{HOME} AND NOT "$ENV{HOME}" STREQUAL "")
+  set(data_home "$ENV{HOME}/.local/share")
+else()
+  message(FATAL_ERROR
+    "XDG_DATA_HOME and HOME are both unset or empty; cannot determine the user data directory")
+endif()
+
+if(NOT DEFINED HELP_SRC OR NOT DEFINED HELP_NAME)
+  message(FATAL_ERROR "HELP_SRC and HELP_NAME are both required")
+endif()
+
+set(dest "${data_home}/help/C/${HELP_NAME}")
+
+# The same filter as the install() rule, so both destinations carry the same tree: the pages and
+# the figures, and nothing an editor left behind.
+file(COPY "${HELP_SRC}/" DESTINATION "${dest}"
+     FILES_MATCHING PATTERN "*.page" PATTERN "*.png" PATTERN "*.jpg")
+
+# Printed because there is no uninstall target: undoing this is these paths.
+file(GLOB_RECURSE installed LIST_DIRECTORIES FALSE RELATIVE "${dest}" "${dest}/*")
+list(SORT installed)
+foreach(path IN LISTS installed)
+  message(STATUS "wrote ${dest}/${path}")
+endforeach()

docs/claude/build-and-run.md

@@ -74,6 +74,28 @@ GApplication id and the install directory at once. The figures are regenerated b
 `tools/make-help-shots.sh`, which drives the app headlessly against the mock and draws the annotation
 boxes with ImageMagick; Mallard is translatable with `itstool`, but only the `C` set is authored.
 
+Because the manual is the only thing udpscope installs, it can be installed *alone* — where `help:`
+finds it, and without the `cmake --install` of a whole project — by either of two opt-in targets.
+Neither is built by default and `cmake --build build` never touches either:
+
+```sh
+cmake --build build --target install-help-user   # <data-home>/help/C/<id>/, no root
+cmake --build build --target install-help         # <CMAKE_INSTALL_PREFIX>/share/help/C/<id>/
+```
+
+`install-help-user` writes to `$XDG_DATA_HOME` when it is set and to `$HOME/.local/share` when it is
+not — the XDG Base Directory Specification's own default for the variable, and the fallback
+`help_installed_path()` uses — so it needs no root and lands the set exactly
+where `F1` and the alert look for it. `install-help` goes through the install machinery into the
+configured `CMAKE_INSTALL_PREFIX`, so a packager or a system-wide user points it at `/usr` with
+`-DCMAKE_INSTALL_PREFIX` at configure time. Neither target can install system-wide by itself: a build
+target has no more privilege than the shell that ran it, so `install-help` writes to the configured
+prefix and a system-wide caller wraps it in `sudo`. Both print where they wrote. Both land the same
+tree the `install()` rule does — the user-local copy applies that rule's file filter, and the
+prefix-wide target *is* that rule, reached through the `Help` component
+(`cmake --install --component Help`) — and the ordinary `cmake --install` still installs every
+component, so its behaviour is unchanged.
+
 Options: `--server`, `--port`, `--multicast`, `--interface`, `--buffer-mb` (per
 buffer, default 200), `--max-window`, `--holdoff`, `--recv-buffer`, `--plots` (the row
 count to *start* with, 1..`RowSet::kMaxRows`; the layout editor owns it afterwards),