landon
6bd44c2ac9
Add an XFCE section to the install guide covering Whisker Menu favourites (right-click → Add to Favorites), panel/desktop launcher alternatives, and menu-refresh commands. Fold XFCE equivalents into the on-screen keyboard, HiDPI, and X11 tips, and add a troubleshooting row. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
257 lines
8.8 KiB
Markdown
257 lines
8.8 KiB
Markdown
# 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](#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](#surface-specific-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.
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
# 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
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
# 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):
|
||
|
||
```sh
|
||
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:
|
||
|
||
```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** —
|
||
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:
|
||
```sh
|
||
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:
|
||
```sh
|
||
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):
|
||
```sh
|
||
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:
|
||
```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.
|
||
|
||
---
|
||
|
||
## Updating
|
||
|
||
```sh
|
||
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
|
||
|
||
```sh
|
||
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. |
|