diff --git a/INSTALL-debian12-surface.md b/INSTALL-debian12-surface.md index 263d2cc..6ef7115 100644 --- a/INSTALL-debian12-surface.md +++ b/INSTALL-debian12-surface.md @@ -1,7 +1,9 @@ # Installing md-manuscript on a Surface tablet (Debian 12 "Bookworm") These steps build the app from source and set it up for touch use on a Microsoft -Surface running Debian 12 with the GNOME desktop. You do **not** need the +Surface running Debian 12. They assume the **GNOME** desktop, with **XFCE** +equivalents called out where they differ (see *[Add md-manuscript to the XFCE +menu](#add-md-manuscript-to-the-xfce-menu)*). You do **not** need the `linux-surface` custom kernel for this app — any working Debian 12 desktop is fine. @@ -85,8 +87,9 @@ hardware. The result is `~/md-manuscript/target/release/md-manuscript`. ## 4. Install the binary and a launcher -Put the binary on your `PATH` and add a GNOME app entry so it appears in the -Activities/app grid and can be pinned to the dash (handy for touch): +Put the binary on your `PATH` and add a desktop app entry so it appears in your +applications menu (GNOME app grid / XFCE Whisker Menu) and can be pinned for +touch: ```sh # 4a. Binary @@ -121,6 +124,49 @@ You can now launch **md-manuscript** by tapping its icon, or run --- +## Add md-manuscript to the XFCE menu + +XFCE reads the same `~/.local/share/applications/md-manuscript.desktop` launcher +from step 4, so the app already appears under **Office** in the applications +menu. To pin it as a favourite: + +**Whisker Menu (Favourites).** The Favourites feature lives in the *Whisker +Menu* (the modern XFCE menu), not the classic *Applications Menu* plugin. Open +the Whisker Menu, type `md-manuscript` (or find it under *Office*), then +**right-click it → "Add to Favorites."** It moves to the Favourites column at the +top-left of the menu, where you can right-click to reorder or remove it. + +If your panel still has the classic *Applications Menu* (which has no +favourites), install and switch to Whisker: + +```sh +sudo apt install -y xfce4-whiskermenu-plugin +``` + +then right-click the panel → *Panel → Add New Items… → Whisker Menu* (and remove +the old menu plugin). + +**Panel launcher (alternative).** To place it directly on the panel: right-click +the panel → *Panel → Add New Items… → Launcher → Add*, then right-click the new +launcher → *Properties*, press **+**, and pick **md-manuscript** from the list. + +**Desktop icon (alternative).** Copy the launcher onto the desktop: + +```sh +cp ~/.local/share/applications/md-manuscript.desktop ~/Desktop/ +``` + +(right-click it → *Allow Launching* the first time, if prompted). + +If it doesn't show up in the menu, refresh the database and restart the panel: + +```sh +update-desktop-database ~/.local/share/applications 2>/dev/null || true +xfce4-panel -r +``` + +--- + ## 5. First run 1. In the top bar, set **Workspace** (default `~/Manuscript`) and tap **Open** — @@ -143,15 +189,19 @@ You can now launch **md-manuscript** by tapping its icon, or run ## Surface-specific tips **On-screen keyboard (detached from Type Cover).** -GNOME Settings → *Accessibility* → *Typing* → turn on **Screen Keyboard**. It -pops up automatically when you tap a text field. For terminal-heavy setup you may -find it easier to attach the keyboard for the one-time install. +GNOME Settings → *Accessibility* → *Typing* → turn on **Screen Keyboard**; it +pops up automatically when you tap a text field. XFCE has no built-in one — install +`onboard` (`sudo apt install -y onboard`) and start it manually. For a +terminal-heavy setup you may find it easier to attach the keyboard for the +one-time install. **HiDPI / tiny or huge UI.** Surface screens are very high resolution. The app follows the desktop's scale factor, so set it once in GNOME Settings → *Displays* → **Scale** (enable -*Fractional Scaling* if you want values like 150%/175%). If you run under X11 and -the size is still off, launch with an explicit factor: +*Fractional Scaling* if you want values like 150%/175%). On XFCE, use *Settings → +Appearance → Fonts → Custom DPI* and/or *Settings → Display*, or raise `Xft/DPI` +in *Settings Editor*. Because XFCE runs on X11, you can also launch with an +explicit factor (this works on GNOME-under-X11 too): ```sh WINIT_X11_SCALE_FACTOR=1.75 md-manuscript ``` @@ -168,6 +218,8 @@ login screen, or force X11 for one launch: ```sh WINIT_UNIX_BACKEND=x11 md-manuscript ``` +XFCE is X11-only on Debian 12, so there is no Wayland toggle to worry about and +the `WINIT_X11_SCALE_FACTOR` variable above applies directly. --- @@ -199,5 +251,6 @@ rm -f ~/.local/share/applications/md-manuscript.desktop | **📂 Browse** buttons do nothing / no dialog appears | Install `xdg-desktop-portal` and `xdg-desktop-portal-gtk` (step 1b); you can still type paths by hand. | | Build error mentioning `rustc … is not supported` | `rustup update`, then `cargo build --release` again. | | `cargo: command not found` | Run `. "$HOME/.cargo/env"` or open a new terminal after installing rustup. | -| UI text far too small/large | Adjust GNOME *Displays → Scale*, or set `WINIT_X11_SCALE_FACTOR` (X11). | +| UI text far too small/large | Adjust GNOME *Displays → Scale* (or XFCE *Appearance → Fonts → Custom DPI*), or set `WINIT_X11_SCALE_FACTOR` (X11). | +| Not in the XFCE menu / no **Add to Favorites** | Run `update-desktop-database ~/.local/share/applications` and `xfce4-panel -r`; favourites need the *Whisker Menu* (`xfce4-whiskermenu-plugin`), not the classic Applications Menu. | | **⟳ Sync** does nothing / errors in the Log panel | Set `git config --global user.name/user.email`, and ensure the `origin` remote and your SSH/HTTPS credentials are configured. |