Open the bundled manual from Help and from Settings

The packages now carry the manual, but nothing in the application opened
it: the help sheet listed gestures and stopped there.

The help sheet gains a Manual button beside Done, and Settings a Manual
row under About beside the version. Both go through dr_ui::manual, which
finds the installed page through dr_plat::system_data_dirs (the package's
share directory on Linux, the executable's directory on Windows), and a
development build also in the checkout it was compiled from. A copy with
no manual says so on the status line rather than doing nothing.

On the desktop the page goes to the system browser. A section is a URL
fragment, and xdg-open's generic mode and Windows' FileProtocolHandler
both turn a file: URL into a path and drop the fragment, so a section is
opened through a one-line redirect page written to the data directory:
the opener gets a plain path, which every opener keeps, and the browser
follows the redirect to index.html#section itself. The launcher behind
the sign-in's open_in_browser is split out so both share it; the https
check stays with the sign-in.

Android has no path to give a browser: an asset is not a file, a copy in
private storage is unreadable to other apps, a file: URI across apps is
refused, and a content: URI leaves the browser resolving every picture
against the provider. So ManualActivity, a WebView reading
file:///android_asset/manual/index.html straight out of the APK, shows
it, started by class name with the section as an extra. JavaScript is
off, links off the page go to the browser, and the theme is day-night so
the page's own light and dark follow the system. A test checks that the
manifest, the Java class and dr_ui agree on the name and the extra.

ui/dr-ui/src/launch_ui.rs

@@ -847,6 +847,16 @@ fn open_in_browser(url: &str) -> std::io::Result<()> {
             format!("refusing to open a sign-in address that is not https: {url}"),
         ));
     }
+    hand_to_system(url)
+}
+
+/// Hand `target` — a URL, or a local file's path — to whatever the platform
+/// opens it with.
+///
+/// No check on what it is: [`open_in_browser`] is the caller with a server's
+/// URL in hand and refuses anything but https before it gets here, and
+/// `manual::open` hands over a page it wrote itself.
+pub(crate) fn hand_to_system(url: &str) -> std::io::Result<()> {
     // Not `target_os = "linux"`: Android is its own target_os, and reached this
     // arm's `Ok(())` fallback, so the browser silently never opened.
     #[cfg(all(unix, not(target_os = "android"), not(target_os = "macos")))]

ui/dr-ui/src/lib.rs

@@ -48,6 +48,7 @@ mod library;
 mod library_ui;
 #[cfg(live_style)]
 mod live_style;
+pub mod manual;
 mod masks_ui;
 pub mod memory;
 pub mod merge;

ui/dr-ui/src/library_ui/grid.rs

@@ -199,6 +199,26 @@ pub fn wire<F>(
                 .collect::<Vec<_>>(),
         )));
 
+    // TRACES: FR-UI-4
+    // The manual, from the help sheet and from Settings. Opened on this
+    // thread: all it does is write a one-line page and start a process (or,
+    // on Android, an activity), which is quicker than handing it to a worker.
+    // A failure — in practice, a build with no manual installed — goes to the
+    // status line, since the button the user pressed otherwise did nothing.
+    {
+        let weak = window.as_weak();
+        window
+            .global::<Library>()
+            .on_library_open_manual(move |anchor| {
+                if let Err(e) = crate::manual::open(&anchor) {
+                    log::warn!("manual: {e}");
+                    if let Some(w) = weak.upgrade() {
+                        w.global::<Library>().set_library_status(e.into());
+                    }
+                }
+            });
+    }
+
     // Shared rather than moved: a click and `Return` both open an image, and
     // they are two callbacks.
     let on_open_image: OpenImage = Rc::new(on_open_image);

ui/dr-ui/src/manual.rs

@@ -0,0 +1,221 @@
+//! TRACES: FR-UI-4
+//! Opening the bundled manual, at a section when asked for one.
+//!
+//! The manual is `docs/manual/index.html` and its pictures, rendered by
+//! `tools/traceability` and installed by each package beside the models:
+//! `/usr/share/darkroom/manual` on Linux, `manual\` beside the executable on
+//! Windows, `assets/manual` inside the APK. Bundled rather than linked to on
+//! the forge, because the moment somebody opens a help sheet is not a moment
+//! to require a network.
+//!
+//! # Desktop: the system browser, by way of a one-line page
+//!
+//! A section is a fragment — `index.html#rating-and-flagging` — and the
+//! fragment is exactly what the platforms' openers lose. `xdg-open` in its
+//! generic mode, and `url.dll,FileProtocolHandler` on Windows, turn a `file:`
+//! URL into a path before they hand it on, and a path has no fragment: the
+//! manual opens at the top and the "See it" link has done nothing a plain
+//! "Manual" link would not. So a section is opened through a small page of
+//! our own whose only content is a redirect to the full URL, fragment and
+//! all; the opener is handed that page's *path*, which every opener keeps
+//! intact, and the browser follows the redirect itself. Written to the user
+//! data directory, overwritten on each use.
+//!
+//! # Android: a WebView of our own
+//!
+//! Android has no path to hand a browser. An asset inside the APK is not a
+//! file; a copy unpacked to app-private storage is a file no other app may
+//! read, and a `file:` URI handed across apps is refused outright since API
+//! 24. A content provider would serve the page, but a browser then asks the
+//! same provider for every picture by a relative URL it resolves against a
+//! `content:` authority — which the browsers do not reliably do. So the page is
+//! shown by `ManualActivity`, a WebView that reads
+//! `file:///android_asset/manual/index.html` straight out of the APK, pictures
+//! and fragment included, with nothing unpacked.
+
+use std::path::PathBuf;
+
+/// The Android activity that shows the manual. Named by string in the Intent,
+/// so no class has to be loaded to start it; the manifest test in
+/// `darkroom-android` checks the manifest declares this exact name.
+pub const ANDROID_ACTIVITY: &str = "paris.tourolle.darkroom.ManualActivity";
+
+/// The Intent extra carrying the section, read by `ManualActivity`.
+pub const ANDROID_EXTRA_ANCHOR: &str = "anchor";
+
+/// Where the installed manual is, if a package installed one.
+///
+/// The package directories first, as the models are found. A development
+/// build also looks in the checkout it was compiled from, so `cargo run`
+/// opens the page the tree has; a release build never does, because the
+/// checkout is not on the user's machine.
+pub fn page() -> Option<PathBuf> {
+    #[allow(unused_mut)]
+    let mut candidates: Vec<PathBuf> = dr_plat::system_data_dirs()
+        .into_iter()
+        .map(|d| d.join("manual").join("index.html"))
+        .collect();
+    #[cfg(debug_assertions)]
+    candidates.push(PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../docs/manual/index.html"));
+    candidates.into_iter().find(|p| p.is_file())
+}
+
+/// A section's anchor, as it may appear in a URL.
+///
+/// Anchors are the forge's slugs — lower-case letters, digits and hyphens — so
+/// anything else in one is not a section of this manual and is dropped rather
+/// than escaped: it came from the generated gesture table, and a table entry
+/// that needs escaping is a bug to notice, not to route around.
+fn clean_anchor(anchor: &str) -> String {
+    anchor
+        .chars()
+        .filter(|c| c.is_alphanumeric() || *c == '-' || *c == '_')
+        .collect()
+}
+
+/// The redirect page for one section of the manual at `target`.
+#[cfg(not(target_os = "android"))]
+fn redirect_page(target: &str) -> String {
+    format!(
+        "<!DOCTYPE html>\n<html lang=\"en\"><head><meta charset=\"utf-8\">\n\
+         <title>DarkRoom manual</title>\n\
+         <meta http-equiv=\"refresh\" content=\"0; url={target}\">\n\
+         </head><body><p><a href=\"{target}\">Open the DarkRoom manual</a></p></body></html>\n"
+    )
+}
+
+/// Open the manual, at `anchor` when it is not empty.
+///
+/// The error is a sentence for the status line: the one case a user can do
+/// anything about is a manual that is not installed.
+pub fn open(anchor: &str) -> Result<(), String> {
+    let anchor = clean_anchor(anchor);
+    #[cfg(target_os = "android")]
+    {
+        android_open(&anchor)
+    }
+    #[cfg(not(target_os = "android"))]
+    {
+        desktop_open(&anchor)
+    }
+}
+
+#[cfg(not(target_os = "android"))]
+fn desktop_open(anchor: &str) -> Result<(), String> {
+    let Some(page) = page() else {
+        return Err("The manual is not installed with this copy of DarkRoom".into());
+    };
+    // Unix only: on Windows `canonicalize` answers with a `\\?\` verbatim
+    // path, which is not one a `file:` URL can be made from — and there the
+    // path is the executable's directory, already absolute.
+    #[cfg(unix)]
+    let page = page.canonicalize().unwrap_or(page);
+    if anchor.is_empty() {
+        log::info!("opening the manual at {}", page.display());
+        return crate::launch_ui::hand_to_system(&page.to_string_lossy())
+            .map_err(|e| format!("Could not open the manual: {e}"));
+    }
+
+    let Ok(mut url) = url::Url::from_file_path(&page) else {
+        return Err(format!(
+            "{} is not a path a browser can open",
+            page.display()
+        ));
+    };
+    url.set_fragment(Some(anchor));
+
+    let link = dr_plat::base_dir(dr_plat::Base::Data).join("manual-link.html");
+    if let Some(dir) = link.parent() {
+        std::fs::create_dir_all(dir).map_err(|e| format!("Could not open the manual: {e}"))?;
+    }
+    std::fs::write(&link, redirect_page(url.as_str()))
+        .map_err(|e| format!("Could not open the manual: {e}"))?;
+    log::info!("opening the manual at {url} by way of {}", link.display());
+    crate::launch_ui::hand_to_system(&link.to_string_lossy())
+        .map_err(|e| format!("Could not open the manual: {e}"))
+}
+
+/// Start `ManualActivity` with the section as an extra.
+///
+/// `Intent.setClassName(Context, String)` rather than a class object: the
+/// activity's class is in this APK's dex, which a native thread's `FindClass`
+/// cannot see (see `darkroom-android`'s `load_class`), and a name needs no
+/// class at all. The extra is a string rather than the Intent's data URI,
+/// because a `file:` data URI trips the platform's exposure check.
+#[cfg(target_os = "android")]
+fn android_open(anchor: &str) -> Result<(), String> {
+    let ctx = ndk_context::android_context();
+    if ctx.vm().is_null() || ctx.context().is_null() {
+        return Err("no Android context available".into());
+    }
+    // SAFETY: the pointer comes from ndk_context, which android-activity fills
+    // in with the process's real JavaVM before any Rust runs.
+    let vm = unsafe { jni::JavaVM::from_raw(ctx.vm().cast()) };
+    let raw_activity: jni::sys::jobject = ctx.context().cast();
+
+    vm.attach_current_thread(|env| {
+        // SAFETY: valid for this frame, which is all the Intent needs.
+        let activity = unsafe { jni::objects::JObject::from_raw(env, raw_activity) };
+        let intent = env.new_object(
+            jni::jni_str!("android/content/Intent"),
+            jni::jni_sig!("()V"),
+            &[],
+        )?;
+        let class = env.new_string(ANDROID_ACTIVITY)?;
+        env.call_method(
+            &intent,
+            jni::jni_str!("setClassName"),
+            jni::jni_sig!("(Landroid/content/Context;Ljava/lang/String;)Landroid/content/Intent;"),
+            &[(&activity).into(), (&class).into()],
+        )?;
+        let key = env.new_string(ANDROID_EXTRA_ANCHOR)?;
+        let value = env.new_string(anchor)?;
+        env.call_method(
+            &intent,
+            jni::jni_str!("putExtra"),
+            jni::jni_sig!("(Ljava/lang/String;Ljava/lang/String;)Landroid/content/Intent;"),
+            &[(&key).into(), (&value).into()],
+        )?;
+        env.call_method(
+            &activity,
+            jni::jni_str!("startActivity"),
+            jni::jni_sig!("(Landroid/content/Intent;)V"),
+            &[(&intent).into()],
+        )?;
+        if env.exception_check() {
+            env.exception_clear();
+            return Err(jni::errors::Error::JavaException);
+        }
+        Ok(())
+    })
+    .map_err(|e: jni::errors::Error| format!("Could not open the manual: {e}"))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn an_anchor_keeps_only_what_a_slug_can_hold() {
+        assert_eq!(clean_anchor("rating-and-flagging"), "rating-and-flagging");
+        assert_eq!(clean_anchor("x\"><script>"), "xscript");
+        assert_eq!(clean_anchor(""), "");
+    }
+
+    #[cfg(not(target_os = "android"))]
+    #[test]
+    fn the_redirect_carries_the_fragment() {
+        let page = redirect_page("file:///usr/share/darkroom/manual/index.html#looking-closer");
+        assert!(page.contains(
+            "content=\"0; url=file:///usr/share/darkroom/manual/index.html#looking-closer\""
+        ));
+    }
+
+    /// A development build finds the page in the checkout, so this is also
+    /// the test that the committed page is where the packagers copy it from.
+    #[test]
+    fn a_development_build_finds_the_page() {
+        let page = page().expect("docs/manual/index.html is not where the packagers expect it");
+        assert!(page.ends_with("index.html"));
+    }
+}