Emacs-KP: Knuth-Plass Line Breaking for Emacs

中文文档 | Developer Guide

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:

(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...

(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.

(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

cd ekp_c
make

Requirements: C11 compiler, Emacs 27.1+

Loading

(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.

Credits

• Core Algorithm: "Breaking Paragraphs into Lines" by Donald E. Knuth and Michael F. Plass (1981)
• Hyphenation: Adapted from Pyphen, using Liang's algorithm
• Dictionaries: Hunspell hyphenation patterns