docs: separate custom text properties and text property layers introduction

Co-authored-by: Kinneyzhang <38454496+Kinneyzhang@users.noreply.github.com>
2026-01-04 13:55:50 +00:00 · 2026-01-04 13:55:50 +00:00 · d7e54e3b3d
commit d7e54e3b3d
parent 01451f44ee
2 changed files with 126 additions and 30 deletions
--- a/README.md
+++ b/README.md
@ -54,7 +54,8 @@
    - [tp-search](#tp-search---search-all-matches)
    - [tp-search-map](#tp-search-map---apply-function-to-matched-text)
 - [The Property Layer System](#the-property-layer-system)
-  - [Custom Text Properties vs Text Property Layers](#custom-text-properties-vs-text-property-layers)
+  - [Custom Text Properties](#custom-text-properties)
+  - [Text Property Layers](#text-property-layers)
  - [Property Layer Concept](#property-layer-concept)
  - [Property Layer Definition](#property-layer-definition)
    - [define-tp / define-tps](#define-tp--define-tps---define-custom-text-properties)
@ -1345,26 +1346,70 @@ Apply FUNCTION to all matches of PROPERTY in OBJECT.

 The **property layer system** is tp.el's innovative feature that allows stacking multiple sets of properties on the same text region. Only the **top layer** is visible, but lower layers are preserved and can be revealed through rotation or pinning.

-### Custom Text Properties vs Text Property Layers
+### Custom Text Properties

-tp.el unifies the concepts of "custom text properties" and "text property layers":
+Custom text properties is a **general-purpose feature** provided by tp.el. After defining with `define-tp`, they can be set using core functions like `tp-set`/`tp-reset`/`tp-add`.

-#### Concept Distinction
+#### Core Features

-1. **Custom Text Properties**: Defined using `define-tp`, when set using `tp-set`/`tp-reset`/`tp-add`, they are treated as regular text properties that can be mixed with built-in Emacs text properties (like `face`, `display`, etc.).
+1. **Mixed Use with Built-in Properties**: Custom text properties can be seamlessly mixed with built-in Emacs text properties (such as `face`, `display`, `help-echo`, etc.).

-2. **Text Property Layers**: Also defined using `define-tp`, but when set using `tp-put-layer`/`tp-push-layer`, layer-related properties are introduced (`tp-name`, `tp-layers`), enabling layer stacking and operations.
-
-3. **Custom Text Property Groups**: Defined using `define-tps`, they contain multiple related text properties that can be used individually or as a group.
-
-#### Definition and Usage
+2. **Automatic Merging of Duplicate Properties**: In a single setting operation, if the same property (e.g., `face`) is specified multiple times, they are automatically merged rather than simply overwritten.

 ```elisp
-;; Define custom text property (layer)
+;; Define a custom text property
 (define-tp tp-highlight ()
  '(face (:background "yellow")))

-;; Use as regular text property (no tp-name or layer attributes)
+;; Mixed use with built-in properties
+(tp-set 1 10 '(tp-highlight t face bold help-echo "tip"))
+;; Result: Has tp-highlight's background color, bold style, and help-echo property
+
+;; Automatic merging of duplicate properties example
+(tp-set "emacs"
+        'face 'bold
+        'face '(:background "green")
+        'face '(:foreground "red"))
+;; Result: face is ((:background "green" :foreground "red") bold)
+;; Three face properties are intelligently merged
+
+;; Later values override earlier ones for the same sub-property
+(tp-set "emacs"
+        'face '(:foreground "red")
+        'face '(:foreground "yellow"))
+;; Result: foreground is "yellow"
+
+;; Use with tp-palette layer
+(tp-set "emacs"
+        'tp-palette 'info
+        'face '(:foreground "red"))
+;; Result: tp-palette's face is merged with (:foreground "red")
+```
+
+#### Custom Text Property Groups
+
+Using `define-tps`, you can define multiple related text property groups that can be used individually or as a group.
+
+---
+
+### Text Property Layers
+
+Text property layers is a **unique feature** of tp.el that requires specific functions (`tp-put-layer`/`tp-push-layer`) to set and use.
+
+#### Core Features
+
+1. **Layer-Related Properties**: When set using `tp-push-layer`/`tp-put-layer`, layer-related properties (`tp-name`, `tp-layers`) are automatically introduced to support layer stacking and operations.
+
+2. **Layer Stacking Mechanism**: Multiple sets of properties can be stacked on the same text region, with only the top layer visible while lower layers are preserved.
+
+3. **Rich Layer Operations**: Supports various layer operations such as rotation, deletion, merging, etc.
+
+```elisp
+;; Define a text property (can be used as custom property or layer)
+(define-tp tp-highlight ()
+  '(face (:background "yellow")))
+
+;; Use as regular custom text property (no layer properties)
 (tp-set 1 10 '(tp-highlight t))
 ;; Result: Only face property, no tp-name

@ -1375,9 +1420,12 @@ tp.el unifies the concepts of "custom text properties" and "text property layers

 #### When to Use Which

- **`tp-set`/`tp-reset`/`tp-add`**: When you only need to set text properties without layer stacking functionality. Suitable for simple property setting scenarios.
-
- **`tp-push-layer`/`tp-put-layer`**: When you need to stack multiple sets of properties on the same text region and perform layer operations like rotation, deletion, etc.
+| Scenario | Recommended Method | Description |
+|----------|-------------------|-------------|
+| Simple property setting | `tp-set`/`tp-reset`/`tp-add` | When you only need to set text properties without layer stacking |
+| Mixed with built-in properties | `tp-set`/`tp-reset`/`tp-add` | Custom properties can be seamlessly mixed with built-in properties |
+| Need layer stacking | `tp-push-layer`/`tp-put-layer` | When you need to stack multiple sets of properties on the same text region |
+| Need layer operations | `tp-push-layer`/`tp-put-layer` | When you need to perform rotation, deletion, and other layer operations |

 ### Property Layer Concept

--- a/README_CN.md
+++ b/README_CN.md
@ -53,7 +53,8 @@
    - [tp-search](#tp-search---搜索所有匹配)
    - [tp-search-map](#tp-search-map---对匹配文本应用函数)
 - [属性层系统](#属性层系统)
-  - [自定义文本属性与文本属性层](#自定义文本属性与文本属性层)
+  - [自定义文本属性](#自定义文本属性)
+  - [文本属性层](#文本属性层)
  - [属性层概念](#属性层概念)
  - [属性层定义](#属性层定义)
    - [define-tp / define-tps](#define-tp--define-tps---定义自定义文本属性)
@ -1339,26 +1340,70 @@ Emacs 的 `text-property-search-forward` 和 `text-property-search-backward` 的

 属性层系统是 tp.el 的创新功能，允许在同一文本区域堆叠多组属性。只有顶层属性可见，但下层属性会被保留，并可通过轮转或固定操作使其显现。

-### 自定义文本属性与文本属性层
+### 自定义文本属性

-tp.el 统一了"自定义文本属性"和"文本属性层"两个概念：
+自定义文本属性是 tp.el 提供的一个**通用功能**。使用 `define-tp` 定义后，可以通过 `tp-set`/`tp-reset`/`tp-add` 等核心函数设置。

-#### 概念辨析
+#### 核心特性

-1. **自定义文本属性**：使用 `define-tp` 定义的文本属性，当使用 `tp-set`/`tp-reset`/`tp-add` 设置时，被认为是普通文本属性，可以和 Emacs 内置的文本属性（如 `face`、`display` 等）混合使用。
+1. **与内置属性混合使用**：自定义文本属性可以和 Emacs 内置的文本属性（如 `face`、`display`、`help-echo` 等）无缝混合使用。

-2. **文本属性层**：同样使用 `define-tp` 定义，但当使用 `tp-put-layer`/`tp-push-layer` 设置时，会引入层相关的属性（如 `tp-name`、`tp-layers`），支持层的堆叠和操作。
-
-3. **自定义文本属性组**：使用 `define-tps` 定义多个相关的文本属性，它们可以单独使用，也可以作为一组使用。
-
-#### 定义与使用
+2. **重复属性自动合并**：在一次设置操作中，如果同一个属性（如 `face`）被指定多次，它们会自动合并，而非简单覆盖。

 ```elisp
-;; 定义自定义文本属性（层）
+;; 定义自定义文本属性
 (define-tp tp-highlight ()
  '(face (:background "yellow")))

-;; 作为普通文本属性使用（不引入 tp-name 等层属性）
+;; 与内置属性混合使用
+(tp-set 1 10 '(tp-highlight t face bold help-echo "提示"))
+;; 结果: 同时具有 tp-highlight 的背景色、bold 样式和 help-echo 属性
+
+;; 重复属性自动合并示例
+(tp-set "emacs"
+        'face 'bold
+        'face '(:background "green")
+        'face '(:foreground "red"))
+;; 结果: face 是 ((:background "green" :foreground "red") bold)
+;; 三个 face 属性被智能合并
+
+;; 同一子属性后面的覆盖前面的
+(tp-set "emacs"
+        'face '(:foreground "red")
+        'face '(:foreground "yellow"))
+;; 结果: foreground 是 "yellow"
+
+;; 与 tp-palette 层配合使用
+(tp-set "emacs"
+        'tp-palette 'info
+        'face '(:foreground "red"))
+;; 结果: tp-palette 的 face 与 (:foreground "red") 合并
+```
+
+#### 自定义文本属性组
+
+使用 `define-tps` 可以定义多个相关的文本属性组，它们可以单独使用，也可以作为一组使用。
+
+---
+
+### 文本属性层
+
+文本属性层是 tp.el 的**独特功能**，需要使用特定的函数（`tp-put-layer`/`tp-push-layer`）才能设置和使用。
+
+#### 核心特性
+
+1. **引入层相关属性**：当使用 `tp-push-layer`/`tp-put-layer` 设置时，会自动引入 `tp-name`、`tp-layers` 等层相关属性，用于支持层的堆叠和操作。
+
+2. **层堆叠机制**：可以在同一文本区域堆叠多组属性，只有顶层可见，下层被保留。
+
+3. **丰富的层操作**：支持轮换、删除、合并等多种层操作。
+
+```elisp
+;; 定义文本属性（可同时用作自定义属性或层）
+(define-tp tp-highlight ()
+  '(face (:background "yellow")))
+
+;; 作为普通自定义文本属性使用（不引入层属性）
 (tp-set 1 10 '(tp-highlight t))
 ;; 结果: 只有 face 属性，没有 tp-name

@ -1369,9 +1414,12 @@ tp.el 统一了"自定义文本属性"和"文本属性层"两个概念：

 #### 何时使用哪种方式

- **`tp-set`/`tp-reset`/`tp-add`**：当你只需要设置文本属性，不需要层堆叠功能时使用。适合简单的属性设置场景。
-
- **`tp-push-layer`/`tp-put-layer`**：当你需要在同一文本区域堆叠多组属性，并进行轮换、删除等层操作时使用。
+| 场景 | 推荐方式 | 说明 |
+|------|----------|------|
+| 简单属性设置 | `tp-set`/`tp-reset`/`tp-add` | 当你只需要设置文本属性，不需要层堆叠功能时 |
+| 与内置属性混合 | `tp-set`/`tp-reset`/`tp-add` | 自定义属性可以和内置属性无缝混合 |
+| 需要层堆叠 | `tp-push-layer`/`tp-put-layer` | 当你需要在同一文本区域堆叠多组属性时 |
+| 需要层操作 | `tp-push-layer`/`tp-put-layer` | 当你需要进行轮换、删除等层操作时 |

 ### 属性层概念