md-manuscript/INSTALL-debian12-surface.md

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. They assume the GNOME desktop, with XFCE equivalents called out where they differ (see 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.

Everything is done in a terminal. If your Surface is detached from its keyboard, turn on the on-screen keyboard first (see Surface tips).

---

1. One-time system setup

a. Build tools

Debian 12 ships Rust 1.63 in apt, which is too old for this project. Install the Rust toolchain with rustup instead, plus a C linker.

sudo apt update
sudo apt install -y build-essential curl git

# Install rustup (choose option 1, the default, when prompted)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Load cargo into the current shell (or just open a new terminal)
. "$HOME/.cargo/env"

rustc --version   # should print 1.8x or newer

b. Runtime GUI libraries

The compiled binary loads its graphics/windowing libraries at runtime (it links against only libc/libgcc). Most are already present under GNOME, but install the full set so it runs on both Wayland and X11:

sudo apt install -y \
  libgl1 libegl1 libgl1-mesa-dri \
  libwayland-client0 libwayland-egl1 libwayland-cursor0 \
  libxkbcommon0 libxkbcommon-x11-0 \
  libx11-6 libx11-xcb1 libxcursor1 libxi6 libxrandr2 libxinerama1 libxrender1

The 📂 Browse buttons open native file dialogs through the XDG Desktop Portal. On GNOME this is already installed, but if the dialogs don't appear, ensure the portal and a file-chooser backend are present:

sudo apt install -y xdg-desktop-portal xdg-desktop-portal-gtk

---

2. Get the source onto the tablet

Copy the md-manuscript project directory to the tablet (via USB, scp, or a sync tool), or clone it if you've pushed it to a git remote:

# Example if you pushed it somewhere:
git clone <your-repo-url> ~/md-manuscript

The rest of these steps assume the source is at ~/md-manuscript.

---

3. Build

cd ~/md-manuscript
cargo build --release

The first build downloads dependencies and takes a few minutes on Surface hardware. The result is ~/md-manuscript/target/release/md-manuscript.

If the build stops with "rustc 1.87.0 is not supported by … image@0.25.x", your Rust is older than expected — run rustup update and rebuild.

---

4. Install the binary and a launcher

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:

./assets/install.sh

That puts the binary on your PATH, installs the icon at every size the desktop might ask for, and adds the launcher — then refreshes both caches. It is safe to re-run after every rebuild, which is how you pick up a new version. Installing somewhere else is PREFIX=/usr/local sudo ./assets/install.sh.

What it does, if you would rather do it by hand

install -Dm755 target/release/md-manuscript ~/.local/bin/md-manuscript

for size in 16 22 24 32 48 64 128 256; do
  install -Dm644 "assets/icons/hicolor/${size}x${size}/apps/md-manuscript.png" \
    ~/.local/share/icons/hicolor/${size}x${size}/apps/md-manuscript.png
done
install -Dm644 assets/icons/hicolor/scalable/apps/md-manuscript.svg \
  ~/.local/share/icons/hicolor/scalable/apps/md-manuscript.svg

install -Dm644 assets/md-manuscript.desktop \
  ~/.local/share/applications/md-manuscript.desktop

gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor 2>/dev/null || true
update-desktop-database ~/.local/share/applications 2>/dev/null || true

The launcher is assets/md-manuscript.desktop, kept in the repository and copied into place rather than typed out at the prompt — a here-document is an awkward thing to paste into a terminal, and this way the launcher is versioned along with everything else.

Icon=md-manuscript in the launcher is a name, not a path: the desktop looks it up in the icon theme and picks whichever size it wants, which is why the whole set gets installed rather than one file. StartupWMClass matches the running window to the launcher, so a pinned icon highlights rather than spawning a second entry.

The window carries the icon itself as well — the 256px PNG is compiled into the binary — so the title bar and the task switcher show it even before any of this is installed.

Regenerating the icon

assets/md-manuscript.svg is the source. After editing it, rebuild the PNG set (ImageMagick rasterises the SVG; Pillow does the downscaling, which is markedly cleaner at 16 and 24 px):

python3 - <<'REGEN'
import os, subprocess
from PIL import Image
subprocess.run(["convert", "-background", "none", "-density", "1200",
                "assets/md-manuscript.svg", "-resize", "512x512",
                "/tmp/md-manuscript-master.png"], check=True)
im = Image.open("/tmp/md-manuscript-master.png").convert("RGBA")
for size in (16, 22, 24, 32, 48, 64, 128, 256):
    d = f"assets/icons/hicolor/{size}x{size}/apps"
    os.makedirs(d, exist_ok=True)
    im.resize((size, size), Image.LANCZOS).save(f"{d}/md-manuscript.png")
REGEN
cp assets/md-manuscript.svg assets/icons/hicolor/scalable/apps/md-manuscript.svg
cargo build --release   # the 256px PNG is baked into the binary

Make sure ~/.local/bin is on your PATH (it is by default on Debian 12 if the directory exists at login — otherwise add this to ~/.bashrc and re-login):

export PATH="$HOME/.local/bin:$PATH"

You can now launch md-manuscript by tapping its icon, or run md-manuscript from a terminal.

---

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:

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:

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:

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 — the folder is created if missing.
2. Tap Init git once to version-control the workspace.
3. To sync across devices, add a remote yourself, then use the ⟳ Sync button:

   cd ~/Manuscript
   git remote add origin <url>
   git push -u origin main
   

   You'll also want to set your git identity once on the tablet:

   git config --global user.name  "Your Name"
   git config --global user.email "you@example.com"
   

---

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. 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%). 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):

WINIT_X11_SCALE_FACTOR=1.75 md-manuscript

Touch gestures.

• Tap a file name to open it.
• Reorder by pressing the ⠿ handle and dragging up/down with your finger.
• Scroll the file list or editor with a one-finger drag.

Wayland vs X11. GNOME on Debian 12 defaults to Wayland; the app supports it natively. If you hit a rendering glitch, log out and pick "GNOME on Xorg" from the gear menu on the login screen, or force X11 for one launch:

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.

---

Updating

cd ~/md-manuscript
git pull                # if you cloned it; otherwise re-copy the source
cargo build --release
install -Dm755 target/release/md-manuscript ~/.local/bin/md-manuscript

Uninstall

rm -f ~/.local/bin/md-manuscript
rm -f ~/.local/share/applications/md-manuscript.desktop
# Your manuscripts in ~/Manuscript and config in ~/.config/md-manuscript are left intact.

---

Troubleshooting

Symptom	Fix
error while loading shared libraries: libGL.so.1 (or similar)	Install the runtime libraries in step 1b.
Window fails with "neither WAYLAND_DISPLAY nor DISPLAY is set"	You're in a text-only session/SSH; run it from the tablet's graphical 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 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.