121 lines
3.6 KiB
Markdown
121 lines
3.6 KiB
Markdown
# Emacs-KP: Knuth-Plass Line Breaking for Emacs
|
|
|
|
[中文文档](./readme_zh.md) | [Developer Guide](./DEVELOPER.md)
|
|
|
|
Emacs-kp implements the Knuth-Plass optimal line breaking algorithm with full support for CJK (Chinese, Japanese, Korean) and Latin mixed text typesetting.
|
|
|
|
## Demo
|
|
|
|
|
|
## Features
|
|
|
|
- **Optimal Line Breaking**: Uses Knuth-Plass algorithm for globally optimal paragraph layout.
|
|
- **CJK Support**: Full support for Chinese, Japanese, Korean with mixed Latin text.
|
|
- **Hyphenation**: Frank Liang's algorithm with language-specific dictionaries.
|
|
- **Text Properties Preserved**: Font faces, colors, and other Emacs text properties are maintained.
|
|
- **C Module Acceleration**: Optional multi-threaded C module for 16-29x speedup.
|
|
- **Automatic Font Handling**: Spacing parameters computed from actual font metrics.
|
|
|
|
---
|
|
|
|
## User Guide
|
|
|
|
### Quick Start
|
|
|
|
1. **Install Dependencies**:
|
|
Ensure you have a C compiler if you plan to use the C module (recommended for performance).
|
|
|
|
2. **Configuration**:
|
|
|
|
```elisp
|
|
(add-to-list 'load-path "/path/to/emacs-kp")
|
|
(require 'ekp)
|
|
|
|
;; Basic usage: justify text to 600 pixels width
|
|
(ekp-pixel-justify "Your paragraph text here..." 600)
|
|
|
|
;; Find optimal width in a range (returns (text . optimal-width))
|
|
(ekp-pixel-range-justify "Your text" 400 800)
|
|
```
|
|
|
|
### Configuration
|
|
|
|
#### Language Settings
|
|
|
|
**`ekp-latin-lang`** (default: `"en_US"`)
|
|
|
|
Primary Latin language for hyphenation. Supported languages are in `dictionaries/` directory:
|
|
- `en_US`, `en_GB` - English
|
|
- `de_DE` - German
|
|
- `fr` - French
|
|
- `es` - Spanish
|
|
- And many more...
|
|
|
|
```elisp
|
|
(setq ekp-latin-lang "de_DE")
|
|
```
|
|
|
|
#### Spacing Parameters
|
|
|
|
Use `ekp-param-set` to configure spacing (in pixels). If not set, defaults are computed automatically from font metrics.
|
|
|
|
```elisp
|
|
(ekp-param-set lws-ideal lws-stretch lws-shrink
|
|
mws-ideal mws-stretch mws-shrink
|
|
cws-ideal cws-stretch cws-shrink)
|
|
```
|
|
|
|
| Parameter Group | Description |
|
|
|:----------------|:------------|
|
|
| `lws-*` | Latin Word Space: between Latin words |
|
|
| `mws-*` | Mixed Word Space: between Latin and CJK |
|
|
| `cws-*` | CJK Word Space: between CJK characters |
|
|
|
|
#### K-P Algorithm Parameters
|
|
|
|
| Variable | Default | Description |
|
|
|:---------|:--------|:------------|
|
|
| `ekp-line-penalty` | 10 | Base cost per line break |
|
|
| `ekp-hyphen-penalty` | 50 | Extra cost for hyphenated breaks |
|
|
| `ekp-adjacent-fitness-penalty` | 100 | Cost for inconsistent line tightness |
|
|
| `ekp-last-line-min-ratio` | 0.5 | Minimum fill ratio for last line |
|
|
| `ekp-looseness` | 0 | Target line count offset (±n lines) |
|
|
|
|
### C Dynamic Module (Recommended)
|
|
|
|
For large texts, the optional C module provides significant performance improvement through multi-threaded parallel computation.
|
|
|
|
#### Building
|
|
|
|
```bash
|
|
cd ekp_c
|
|
make
|
|
```
|
|
*Requirements: C11 compiler, Emacs 27.1+*
|
|
|
|
#### Loading
|
|
|
|
```elisp
|
|
(require 'ekp-utils)
|
|
|
|
;; Load and initialize C module
|
|
(ekp-c-module-load)
|
|
|
|
;; Optional: Load hyphenation dictionary for C module
|
|
(ekp-c-load-dictionary "en_US")
|
|
```
|
|
|
|
Once loaded, `ekp-use-c-module` defaults to `t`, and all justification functions will automatically use the C module.
|
|
|
|
---
|
|
|
|
## Algorithm & Architecture
|
|
|
|
For a detailed explanation of the internal architecture, algorithms, and API reference, please refer to the **[Developer Guide](./DEVELOPER.md)**.
|
|
|
|
## Credits
|
|
|
|
- **Core Algorithm**: ["Breaking Paragraphs into Lines"](https://gwern.net/doc/design/typography/tex/1981-knuth.pdf) by Donald E. Knuth and Michael F. Plass (1981)
|
|
- **Hyphenation**: Adapted from [Pyphen](https://github.com/Kozea/Pyphen), using Liang's algorithm
|
|
- **Dictionaries**: [Hunspell hyphenation patterns](https://github.com/Kozea/Pyphen)
|