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:

# 4a. Binary
install -Dm755 target/release/md-manuscript ~/.local/bin/md-manuscript

# 4b. Desktop launcher
mkdir -p ~/.local/share/applications
cat > ~/.local/share/applications/md-manuscript.desktop <<'EOF'
[Desktop Entry]
Type=Application
Name=md-manuscript
Comment=Draggable markdown manuscript editor with git sync and ODT export
Exec=md-manuscript
Icon=text-editor
Categories=Office;TextEditor;
Terminal=false
EOF

# 4c. Refresh the app list
update-desktop-database ~/.local/share/applications 2>/dev/null || true

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.