# FAQ

## Where can I download LaTeXSnipper?

Download the latest installers from the [GitHub Releases](https://github.com/SakuraMathcraft/LaTeXSnipper/releases) page.

## Where is the full user manual?

The source manual is kept in `user_manual/` as Markdown and Typst. The generated PDF is rebuilt from `user_manual/user_manual.typ` and may be distributed as a release asset.

## Which platforms are supported?

LaTeXSnipper provides release builds for Windows, Linux, and macOS.

## What differs between Windows, Linux, and macOS?

The main application behavior is intentionally aligned across all three platforms: screenshot recognition, image recognition, PDF recognition, handwriting recognition, export, history, favorites, and the math workbench use the same UI flow.

The main differences are platform integration details:

| Area | Windows | Linux | macOS |
|---|---|---|---|
| Global screenshot hotkey | Native Win32 global hotkey. | `pynput` global hotkey; X11 is the most reliable path, while Wayland/compositor policy can block global shortcuts. | Native Carbon global hotkey. |
| User-configurable hotkeys | `Ctrl+letter` and `Ctrl+Shift+letter`. | `Ctrl+letter` and `Ctrl+Shift+letter`. | `Command+letter` / `Command+Shift+letter` for non-reserved keys; `Option+Command` variants are also supported. |
| Default hotkey | `Ctrl+F`. | `Ctrl+F`. | `Command+F`. |
| Screenshot capture | Qt overlay. | Qt overlay first, then optional CLI/portal fallbacks such as `grim`, `maim`, and `gnome-screenshot`. | Qt overlay with native `screencapture` fallback; macOS may ask for Screen Recording permission. |
| Window close / background behavior | Closing the main window hides it to the system tray; use the tray menu to exit. | Closing the main window hides it to the system tray when a tray is available; without a tray, the app asks before exiting. | Closing the main window minimizes it while the app keeps running; Dock/menu Quit exits the app. |
| Permission model | No explicit screenshot permission is required for the normal capture path. | Wayland compositors can restrict global shortcuts or screenshot capture. | Screen Recording permission is required for screenshots. The native Carbon hotkey path normally does not require Accessibility permission. |
| Dependency runtime | GitHub builds start from the bundled dependency root `<install-dir>\_internal\deps`; users may switch to another root. | Defaults to `~/.latexsnipper/deps`; users may switch to another root. | Defaults to `~/Library/Application Support/LaTeXSnipper/deps`; users may switch to another root. |
| Packaging | Inno installer from GitHub Releases. | Debian/Ubuntu `.deb`. | `.dmg` and `.app.zip`. |

The shortcut UI uses the platform's primary modifier: `Ctrl` on Windows/Linux and `Command` on macOS. macOS system and editing shortcuts such as `Command+Q`, `Command+H`, `Command+M`, `Command+W`, `Command+A`, `Command+C`, `Command+V`, `Command+X`, `Command+Z`, `Command+Space`, `Command+Tab`, and screenshot shortcuts are intentionally rejected; use an `Option+Command` combination when a plain Command shortcut is reserved.

## Which installer should I use?

- Windows: use `LaTeXSnipperSetup-<version>.exe` from GitHub Releases. The release workflow prefers the signed installer; if signing is unavailable, the same filename may be published as an unsigned fallback.
- Linux: use the `.deb` package on Debian/Ubuntu-compatible systems.
- macOS: use the `.dmg` or `.app.zip` artifact.

## Why does macOS still say Screen Recording is unavailable after I enabled it?

LaTeXSnipper checks access with `CGPreflightScreenCaptureAccess()` before each
capture attempt. If access is missing, it requests it once with
`CGRequestScreenCaptureAccess()` and then opens the relevant System Settings
page. macOS associates this permission with the process that performs capture,
so the correct entry depends on how the application was started:

- For a packaged application opened from `/Applications/LaTeXSnipper.app`,
  authorize that exact `LaTeXSnipper` entry in **System Settings -> Privacy &
  Security -> Screen & System Audio Recording**. Older macOS versions call this
  pane **Screen Recording**.
- For a source checkout started with `python src/main.py`, authorize the entry
  that System Settings actually shows for the launch process, such as Python,
  Terminal, iTerm, or VS Code. It is not necessarily named LaTeXSnipper.
- Do not keep running the app directly from a mounted DMG, Downloads, or an
  App Translocation path. Move `LaTeXSnipper.app` to `/Applications`, quit with
  `Command+Q`, then relaunch that same copy before granting permission.

After changing the toggle, use `Command+Q` to quit the application completely;
closing the red window button alone does not exit the macOS app process. Open
the application again from the same location. If a development or test machine
has a stale TCC decision, reset it manually in Terminal and retry; the app never
runs these commands automatically:

```bash
tccutil reset ScreenCapture
# Packaged application only; the bundle identifier is stable.
tccutil reset ScreenCapture com.mathcraft.latexsnipper
```

If the permission preflight succeeds but capture still returns an empty image,
the failure is reported separately from OCR. Check the selected region,
multi-display layout, and `~/Library/Logs/LaTeXSnipper/` for Qt or
`screencapture` diagnostics.

## What is the Office plugin direction?

LaTeXSnipper Office integration is developed in the Windows-native `office_plugin` tree. The plugin provides persistent Ribbon loading, native KeyTip shortcuts, Word OLE and OMML formula insertion, PowerPoint OLE and PNG formula insertion, managed formula metadata, Word automatic numbering/references, and screenshot OCR through the local Bridge recognition boundary without requiring Microsoft 365 enterprise deployment.

## Does LaTeXSnipper require an internet connection?

Core editing and local recognition workflows are designed to work locally after the required dependencies and models are installed. Some optional downloads, update checks, model downloads, and CDN fallbacks require network access.

## Where are dependency files stored?

`install_base_dir` is the active dependency root. Windows packaged builds start
with `<install-dir>\_internal\deps`; Linux defaults to `~/.latexsnipper/deps`;
macOS defaults to `~/Library/Application Support/LaTeXSnipper/deps`. If the user
changes the dependency directory, only the isolated Python dependency
environment follows the new root.

Within that root, LaTeXSnipper creates:

- `python311` for the isolated dependency Python/venv.

App-managed optional tools are shared under the app state root, independent of
the active dependency root:

- `tools/pandoc` for the optional app-managed Pandoc binary.

Pandoc does not follow the active dependency root. It is deployed once under the
app-managed tools directory and remains available after the user switches Python
dependency roots.

Linux/macOS release packages do not bundle build-machine environments from `tools/deps/`.

## When does the dependency wizard initialize pip?

The dependency wizard opens before running `ensurepip`, `pip` upgrade, or `setuptools`/`wheel` repair. Those steps run only after the user starts dependency installation.

If the selected directory already contains a usable Python environment, the wizard uses that interpreter and installs the selected layers there. Windows packaged builds use the bundled `python311` template by default; if the user switches to a directory without a reusable Python, all platforms use a supported system Python (`>=3.10,<3.13`) to create the isolated environment.

## Why do Linux and macOS need Python 3?

The packaged app itself does not run on the user's system Python. Linux and macOS use system Python `>=3.10,<3.13` only to create the isolated optional dependency environment under the active dependency root. Python 3.11 is preferred because it matches the Windows bundled runtime; Python 3.13+ is intentionally rejected until all dependency layers are verified against it.

Linux `.deb` packages declare `python3` and `python3-venv`. macOS users should install a supported Python, preferably Homebrew `python@3.11` or the official python.org 3.11/3.12 macOS installer, if no usable `python3` is available.

## Where are logs stored?

- Windows: `%USERPROFILE%\.latexsnipper\logs\`
- Linux: `~/.latexsnipper/logs/`
- macOS: `~/Library/Logs/LaTeXSnipper/`

If the app crashes, include `crash-native.log` when reporting the issue.

## Where are MathCraft OCR models stored?

- Windows: `%APPDATA%\MathCraft\models\`
- Linux: `${XDG_DATA_HOME:-~/.local/share}/LaTeXSnipper/MathCraft/models/`
- macOS: `~/Library/Application Support/LaTeXSnipper/MathCraft/models/`

If a model download is interrupted or corrupted, delete the affected model subdirectory and restart LaTeXSnipper.

## What should I do if MathCraft OCR does not start?

Run the dependency wizard first. If the issue persists, check the logs and verify the model cache with:

```bash
python -m mathcraft_ocr models check
```

For GPU-related ONNX Runtime failures, use CPU mode:

```bash
MATHCRAFT_FORCE_ORT_CPU=1
```

## Does Linux/macOS bundle Python like Windows?

No. Windows has a normalized bundled Python template. Linux/macOS packages contain the PyInstaller app and create a user-writable dependency environment on demand. This avoids permission errors and prevents build-host virtual environments from leaking into release packages.

## What if Linux fails with EGL, GLOzone, or GPU display errors?

This is usually a Qt WebEngine graphics-backend problem, not a MathCraft GPU inference problem. LaTeXSnipper automatically enables a software-rendering fallback for high-risk Linux sessions such as Wayland, virtual machines, WSL, or systems without `/dev/dri/renderD*`.

Manual overrides:

```bash
LATEXSNIPPER_FORCE_LINUX_GRAPHICS_FALLBACKS=1 latexsnipper
LATEXSNIPPER_DISABLE_LINUX_GRAPHICS_FALLBACKS=1 latexsnipper
```

## Why does screenshot capture behave differently on Wayland?

Wayland restricts application-level screen capture. LaTeXSnipper uses Qt capture first and can fall back to tools such as `grim`, `maim`, or `gnome-screenshot` when available. These system tools are installed by the user or distribution package manager, not by LaTeXSnipper.

## Why is Pandoc optional?

Pandoc is only needed for the optional desktop export formats: Word `.docx`, ODT `.odt`, PowerPoint `.pptx`, EPUB `.epub`, PDF `.pdf`, standalone HTML `.html`, Typst `.typ`, and plain text `.txt`. PDF export also requires a LaTeX PDF engine such as XeLaTeX, LuaLaTeX, or pdfLaTeX. Core recognition, editing, preview, handwriting, and built-in LaTeX/Markdown/MathML/HTML/SVG exports work without Pandoc.

The dependency wizard manages the optional `PANDOC` layer. Manually downloaded or generated Pandoc binaries should not live under `src/`; local developer/build tools belong under `tools/deps/` or the app-managed dependency directory.

## How does PDF recognition work?

Use the main window's PDF recognition button and choose the page count, output format, and render DPI. Built-in MathCraft PDF recognition uses mixed mode because PDF pages need both text and formula recovery. External providers must be configured first; MinerU native mode uses document parsing and returns Markdown.

The PDF result window lets you edit, copy, and save the recognized document. Markdown saves also copy structured image assets when the provider returns them.

## Which external model protocols are supported?

LaTeXSnipper supports the built-in MathCraft OCR path and external providers such as Ollama, OpenAI-compatible APIs, and MinerU-style services. Recommended presets include GLM-OCR, PaddleOCR-VL, Qwen2.5/Qwen3-VL, and MinerU Native. For external providers, configure the protocol, Base URL, model name, API key when required, output preference, timeout, and prompt template.

The Base URL is the service root or the provider's `/v1` API prefix, not a concrete endpoint. The app appends protocol routes itself: Ollama uses `/api/tags` and `/api/chat`, OpenAI-compatible services use `/models` and `/chat/completions` under the resolved `/v1` prefix, and MinerU uses the configured health and parse paths.

External output preference affects normal image, screenshot, and handwriting recognition. PDF recognition asks for output format and DPI at the PDF entry point.

## Why does Ollama fail when I use `/v1`?

Ollama's native API does not use `/v1` for its model list. Use the Ollama protocol and test `http://127.0.0.1:11434/api/tags` first.

## How should I report a bug?

Open a GitHub Issue with:

- Operating system and package type
- Exact reproduction steps
- Full error text or screenshot
- The full `logs` directory
- `crash-native.log` if present
- External model configuration details if the issue involves an external provider

Issues without logs are usually not actionable.

## Which Python environment should contributors use?

Use `tools/deps/python311` for local development, checks, packaging helpers, and IDE integration. The repository-root `python311/` is the Windows template runtime and must not be polluted with development packages or used for ruff, pyright, pytest, or builds.
