9.11.1 Terminal Applications ¶

Use M-x shell for ordinary line-oriented shell commands. For a full terminal, follow EAT Terminal Access, or use built-in Term when no additional package is wanted. Their input, review, and asynchronous feedback models differ; choose the appropriate chapter rather than transferring terminal keys from one application to another.

In Shell/comint, C-e S opens focused speech settings. s toggles automatic output speech and b toggles background monitoring. Background reading needs automatic speech enabled. Both settings affect the captured buffer for its lifetime; this menu has no Save action. q returns to the originating entry or closes a directly opened focused menu.

In WSL Shell buffers, command-name completion skips Windows drive directories by default. Scanning large directories such as C:\Windows\System32 can otherwise pause Emacs. Windows programs still run by name, and explicit filename completion, including /mnt/c/ paths, remains available. To include Windows command names again, use M-x customize-option RET emacsvox-shell-complete-windows-commands RET. This option does not change native Windows or remote Shell buffers.

9.11.2 Forms Mode ¶

Forms presents records from a structured text file one at a time. Emacsvox speaks fields, record movement, searches, and state changes. Forms requires a format specification; see Forms Mode in The GNU Emacs Manual for setup and emacsvox-forms in the Emacsvox Reference Manual for speech.

9.11.3 OCR And PDF-To-Text With PaddleOCR ¶

Emacsvox uses PaddleOCR PP-StructureV3 to turn an image or PDF into UTF-8 Markdown text. It recovers reading order and represents recognised tables as Markdown or embedded HTML. Keep .md output when structure matters; Markdown is plain text and can be named .txt when its lightweight markup is acceptable.

This route is intended for scanned or image-only PDFs. For a born-digital PDF with a trustworthy text layer, extracting that layer is faster and usually more exact than OCR. Recognition still depends on scan quality; upright, high-contrast pages at 300 DPI are a useful starting point.

1. Prepare the isolated OCR environment

   The supported baseline is CPU-only x86-64 WSL2 or GNU/Linux. Paddle’s Linux wheel requires an AVX-capable x86-64 processor and Python 3.9 through 3.13. Do not use Ubuntu 26.04’s Python 3.14 for this environment. The commands below install Python 3.13 separately without altering Emacsvox, system Python, or another project’s packages. Installation uses about 1.7 GB; the first complete PP-StructureV3 run downloads approximately another 1.8 GB of models, cached for later runs.

   Follow the uv installation guide if uv is unavailable, then create the environment:

   uv python install 3.13
   uv venv --python 3.13 --seed \
     "$HOME/.local/share/emacsvox/paddleocr-venv"
   

   Install the tested CPU runtime and PaddleOCR’s all variant, which includes the document-parsing, table, and formula dependencies:

   "$HOME/.local/share/emacsvox/paddleocr-venv/bin/python" -m pip install \
     paddlepaddle==3.3.0 \
     -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
   "$HOME/.local/share/emacsvox/paddleocr-venv/bin/python" -m pip install \
     'paddleocr[all]==3.7.0'
   

   From the checkout, verify that the launcher finds both packages:

   ./bin/emacsvox-paddleocr --check
   

   For a Debian installation, use the installed launcher, here and in the recognition commands below:

   /usr/share/emacsvox/bin/emacsvox-paddleocr --check
   

   The expected report names PaddlePaddle 3.3.0, PaddleOCR 3.7.0, and the CPU device. A missing ccache warning is harmless for normal inference.

   oneDNN, formerly MKL-DNN, is an optional CPU execution backend, not an OCR model. The launcher leaves it disabled because PaddlePaddle 3.3.0 has an upstream PIR-to-oneDNN conversion defect. In the tested pipeline this aborts initialisation at the formula model, although that model is not itself at fault. Standard CPU kernels keep every recognition feature enabled, including tables and formulas. The trade-off is speed, not capability.

2. Recognise and read a document

   For one image, redirect the clean Markdown result to a file. Model downloads and progress go to standard error, not the recognised text:

   ./bin/emacsvox-paddleocr "/path/to/page.png" > page.md
   

   PDF input uses the same command. Paddle renders and recognises every page, then joins them in reading order:

   ./bin/emacsvox-paddleocr "/path/to/scanned-document.pdf" > document.md
   

   A large PDF can require substantial CPU time: table, layout, formula, orientation, and unwarping models are all active by default.

   Inside Emacsvox, press C-e C-o or run M-x emacsvox-ocr RET. In the OCR buffer, o selects an image or PDF. Recognition runs asynchronously and adds its result as a new page when complete. Listen for the completion cue, then use SPC to read the current result, s to save it, or w to save the whole OCR buffer. [ and ] move between results. d opens the per-user OCR directory. Progress and errors are retained separately in *Emacsvox OCR Errors*.

3. Configure recognition and diagnose the adapter

   Use M-x customize-group RET emacsvox-ocr RET for ordinary Emacs configuration rather than shell environment variables. The bundled adapter provides typed options:

   • emacsvox-ocr-paddleocr-python selects an exact Python executable; nil uses the isolated installation above.
   • emacsvox-ocr-paddleocr-language and emacsvox-ocr-paddleocr-device choose recognition language and device.
   • emacsvox-ocr-paddleocr-use-table-recognition and emacsvox-ocr-paddleocr-use-formula-recognition control the structural models; both default to enabled.
   • emacsvox-ocr-paddleocr-use-document-orientation, emacsvox-ocr-paddleocr-use-document-unwarping, and emacsvox-ocr-paddleocr-use-text-line-orientation control image correction.
   • emacsvox-ocr-paddleocr-enable-mkldnn enables oneDNN/MKL-DNN acceleration, not an OCR model. Keep it disabled for the tested PaddlePaddle 3.3.0 CPU setup on WSL.

   These options apply only when emacsvox-ocr-engine names the bundled adapter. A different engine retains the generic interface. emacsvox-ocr-engine-options is an advanced list of literal arguments; for the bundled adapter it follows, and can override, the typed options.

   For standalone shell or automation use, EMACSVOX_PADDLEOCR_VENV changes the environment directory, EMACSVOX_PADDLEOCR_PYTHON selects an executable, and EMACSVOX_PADDLEOCR_LANGUAGE or EMACSVOX_PADDLEOCR_DEVICE changes defaults. See ./bin/emacsvox-paddleocr --help for switches. These environment settings are not the primary Emacs configuration interface.

   Direct SANE scanner-acquisition commands remain for compatibility but are not part of this tested WSL baseline. Scan with a Windows application and select the resulting image or PDF with o when that is the available acquisition route. Scanner configuration is independent of PaddleOCR.