121 lines
3.2 KiB
Markdown
121 lines
3.2 KiB
Markdown
# Emacs-KP: Knuth-Plass 排版算法 Emacs 实现
|
||
|
||
[English Documentation](./readme.md) | [开发者指南](./DEVELOPER_ZH.md)
|
||
|
||
Emacs-kp 实现了 Knuth-Plass 最优断行算法，并扩展支持 CJK（中日韩）与拉丁文混合排版。
|
||
|
||
## 演示
|
||
|
||
|
||
## 特性
|
||
|
||
- **全局最优断行**：使用 Knuth-Plass 算法寻找段落的全局最优布局。
|
||
- **CJK 支持**：完美支持中日韩与拉丁文的混合排版。
|
||
- **连字符断词**：使用 Frank Liang 算法和特定语言词典。
|
||
- **属性保留**：排版后保留字体、颜色等所有 Emacs 文本属性。
|
||
- **C 模块加速**：可选的多线程 C 模块提供 16-29 倍性能提升。
|
||
- **自动字体处理**：根据实际字体度量自动计算间距参数。
|
||
|
||
---
|
||
|
||
## 用户指南
|
||
|
||
### 快速开始
|
||
|
||
1. **安装依赖**：
|
||
建议安装 C 编译器以构建高性能模块。
|
||
|
||
2. **配置与使用**：
|
||
|
||
```elisp
|
||
(add-to-list 'load-path "/path/to/emacs-kp")
|
||
(require 'ekp)
|
||
|
||
;; 基本用法：将文本按 600 像素宽度对齐
|
||
(ekp-pixel-justify "这是一段测试文本..." 600)
|
||
|
||
;; 范围对齐：寻找 400-800 像素范围内的最优宽度
|
||
(ekp-pixel-range-justify "测试文本" 400 800)
|
||
```
|
||
|
||
### 配置详情
|
||
|
||
#### 语言设置
|
||
|
||
**`ekp-latin-lang`** (默认: `"en_US"`)
|
||
|
||
用于断词的主要拉丁语言。支持的语言位于 `dictionaries/` 目录：
|
||
- `en_US`, `en_GB` - 英语
|
||
- `de_DE` - 德语
|
||
- `fr` - 法语
|
||
- `es` - 西班牙语
|
||
- 等等...
|
||
|
||
```elisp
|
||
(setq ekp-latin-lang "de_DE")
|
||
```
|
||
|
||
#### 间距参数
|
||
|
||
使用 `ekp-param-set` 配置间距（像素）。若不设置，将根据字体自动计算。
|
||
|
||
```elisp
|
||
(ekp-param-set lws-ideal lws-stretch lws-shrink
|
||
mws-ideal mws-stretch mws-shrink
|
||
cws-ideal cws-stretch cws-shrink)
|
||
```
|
||
|
||
| 参数组 | 说明 |
|
||
|:-------|:-----|
|
||
| `lws-*` | 拉丁词间距 (Latin Word Space) |
|
||
| `mws-*` | 中西文间距 (Mixed Word Space) |
|
||
| `cws-*` | CJK 字符间距 (CJK Word Space) |
|
||
|
||
#### K-P 算法参数
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|:-----|:-------|:-----|
|
||
| `ekp-line-penalty` | 10 | 每行断行的基础惩罚 |
|
||
| `ekp-hyphen-penalty` | 50 | 连字符断词的惩罚 |
|
||
| `ekp-adjacent-fitness-penalty` | 100 | 相邻行松紧度不一致的惩罚 |
|
||
| `ekp-last-line-min-ratio` | 0.5 | 末行最小填充比例 |
|
||
| `ekp-looseness` | 0 | 目标行数偏移（±n 行） |
|
||
|
||
### C 动态模块 (推荐)
|
||
|
||
对于长文本，建议使用 C 模块以获得显著的性能提升。
|
||
|
||
#### 构建
|
||
|
||
```bash
|
||
cd ekp_c
|
||
make
|
||
```
|
||
*要求：C11 编译器，Emacs 27.1+*
|
||
|
||
#### 加载
|
||
|
||
```elisp
|
||
(require 'ekp-utils)
|
||
|
||
;; 加载并初始化 C 模块
|
||
(ekp-c-module-load)
|
||
|
||
;; 可选：为 C 模块加载断词字典
|
||
(ekp-c-load-dictionary "en_US")
|
||
```
|
||
|
||
加载后，`ekp-use-c-module` 默认为 `t`，所有排版函数将自动使用 C 模块进行加速。
|
||
|
||
---
|
||
|
||
## 算法与架构
|
||
|
||
关于内部架构、算法细节和 API 参考的详细说明，请参阅 **[开发者指南](./DEVELOPER_ZH.md)**。
|
||
|
||
## 致谢
|
||
|
||
- **核心算法**: ["Breaking Paragraphs into Lines"](https://gwern.net/doc/design/typography/tex/1981-knuth.pdf) by Donald E. Knuth and Michael F. Plass (1981)
|
||
- **断词算法**: 改编自 [Pyphen](https://github.com/Kozea/Pyphen)，使用 Liang 算法
|
||
- **词典**: [Hunspell 断词模式](https://github.com/Kozea/Pyphen)
|