From 18ce8798f90c03164d8b03f178f404e2d951e364 Mon Sep 17 00:00:00 2001
From: h-east <h.east.727@gmail.com>
Date: Sat, 19 Jul 2025 12:58:24 +0900
Subject: [PATCH] Update diff.{txt,jax}

---
 doc/diff.jax | 130 +++++++++++++++++++++++++++++++++++++++++++++++++--
 en/diff.txt  | 129 ++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 253 insertions(+), 6 deletions(-)

diff --git a/doc/diff.jax b/doc/diff.jax
index 7cc599491..0ad706fe7 100644
--- a/doc/diff.jax
+++ b/doc/diff.jax
@@ -1,4 +1,4 @@
-*diff.txt*      For Vim バージョン 9.1.  Last change: 2025 Jun 20
+*diff.txt*      For Vim バージョン 9.1.  Last change: 2025 Jul 26
 
 
 		VIMリファレンスマニュアル    by Bram Moolenaar
@@ -14,7 +14,8 @@
 2. 差分を眺める			|view-diffs|
 3. 差分へ移動する		|jumpto-diffs|
 4. 差分を写す			|copy-diffs|
-5. 差分モードのオプション	|diff-options|
+5. 差分アンカー			|diff-anchors|
+6. 差分モードのオプション	|diff-options|
 
 ==============================================================================
 1. 差分モードを開始する					*start-vimdiff*
@@ -343,7 +344,130 @@ Vimは片方のウィンドウには存在しないがもう一方には存在
 				用する (例, "file.c.v2")
 
 ==============================================================================
-5. 差分モードオプション					*diff-options*
+5. 差分アンカー						*diff-anchors*
+
+差分アンカーを使用すると、差分アルゴリズムがファイル間でテキストを揃えて同期さ
+せる位置を制御できる。各アンカーは各ファイル内で互いにマッチするため、差分の出
+力を制御できる。
+
+これは、変更に複雑な編集が含まれる場合に便利である。例えば、関数が別の場所に移
+動され、さらに編集された場合などである。デフォルトでは、アルゴリズムは最小の差
+分を作成することを目指す。その結果、その関数全体が削除され、反対側に追加された
+とみなされ、実際の編集内容を把握することが困難になる。差分アンカーを使用してそ
+の関数をピン留めすることで、差分アルゴリズムはそれに基づいて調整を行う。
+
+使用するには、各ファイル内の {address} をコンマ区切りでリスト化した
+'diffanchors' を使ってアンカーを設定し、'diffopt' に "anchor" を追加する。Vim
+は内部的に各ファイルをアンカーによって分割されたセクションに分割する。そして、
+各セクションのペアごとに個別に diff を実行し、結果をマージする。
+
+'diffanchors' を設定すると、差分が即座に更新される。アンカーがマークに結び付け
+られており、マークの参照先を変更した場合は、更新された差分結果を取得するため
+に、後で手動で |:diffupdate| を呼び出す必要がある。
+
+例:
+
+以下のファイルが並んでいるとする。ここで注目したいのは、編集と移動の両方が行わ
+れた関数 `foo()` の変更点である。
+
+ファイル A: >
+	int foo() {
+	    int n = 1;
+	    return n;
+	}
+
+	int g = 1;
+
+	int bar(int a) {
+	    a *= 2;
+	    a += 3;
+	    return a;
+	}
+ファイル B: >
+	int bar(int a) {
+	    a *= 2;
+	    a += 3;
+	    return a;
+	}
+
+	int foo() {
+	    int n = 999;
+	    return n;
+	}
+
+	int g = 1;
+<
+通常の差分では、通常、以下のように差分結果が整列される: >
+
+	int foo() {     |----------------
+	    int n = 1;  |----------------
+	    return n;   |----------------
+	}               |----------------
+	                |----------------
+	int g = 1;      |----------------
+	                |----------------
+	int bar(int a) {|int bar(int a) {
+	    a *= 2;     |    a *= 2;
+	    a += 3;     |    a += 3;
+	    return a;   |    return a;
+	}               |}
+	----------------|
+	----------------|int foo() {
+	----------------|    int n = 999;
+	----------------|    return n;
+	----------------|}
+	----------------|
+	----------------|int g = 1;
+<
+我々が望むのは、代わりに差分を `foo()` で揃えることである: >
+
+	----------------|int bar(int a) {
+	----------------|    a *= 2;
+	----------------|    a += 3;
+	----------------|    return a;
+	----------------|}
+	----------------|
+	int foo() {     |int foo() {
+	    int n = 1;  |    int n = 999;
+	    return n;   |    return n;
+	}               |}
+	                |
+	int g = 1;      |int g = 1;
+	                |----------------
+	int bar(int a) {|----------------
+	    a *= 2;     |----------------
+	    a += 3;     |----------------
+	    return a;   |----------------
+	}               |----------------
+<
+
+以下に、上記の結果を得るための差分アンカーの設定方法をいくつか示す。各例におい
+て、この設定を有効にするには、'diffopt' に `anchor` が設定されている必要があ
+る。
+
+マーク: アンカーを設定する前に、各ファイルの `int foo()` 行に |'a| マークを設
+定する: >
+	set diffanchors='a
+
+パターン:  |pattern| (|:/| を参照) を使用してアンカーを指定する。ここでは、一
+貫性を保つために、常に 1 行目から検索を開始するようにしている: >
+	set diffanchors=1/int\ foo(/
+<
+選択: ビジュアルモードを使用して、各ファイルの `foo()` 関数本体全体を選択する。
+ここでは 2 つのアンカーを使用している。これにより、関数本体のみが互いにアンカー
+され、それ以降の行はアンカーされないようになる。Note 下の `'>+1` に注目。
+"+1" が必要なのは、関数の最終行の上ではなく下で分割が行われるようにするためで
+ある: >
+	set diffanchors='<,'>+1
+<
+バッファローカルなオプションを介して行番号を使用し 2 つのアンカーを手動で設定
+する: >
+	setlocal diffanchors=1,5
+	wincmd w
+	setlocal diffanchors=7,11
+<
+==============================================================================
+6. 差分モードオプション					*diff-options*
 
 |'diffopt'| と |'fillchars'| の "diff" 項目も参照。
 
diff --git a/en/diff.txt b/en/diff.txt
index 493c740ad..97577fd7b 100644
--- a/en/diff.txt
+++ b/en/diff.txt
@@ -1,4 +1,4 @@
-*diff.txt*      For Vim version 9.1.  Last change: 2025 Jun 20
+*diff.txt*      For Vim version 9.1.  Last change: 2025 Jul 26
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -14,7 +14,8 @@ The basics are explained in section |08.7| of the user manual.
 2. Viewing diffs		|view-diffs|
 3. Jumping to diffs		|jumpto-diffs|
 4. Copying diffs		|copy-diffs|
-5. Diff options			|diff-options|
+5. Diff anchors			|diff-anchors|
+6. Diff options			|diff-options|
 
 ==============================================================================
 1. Starting diff mode					*start-vimdiff*
@@ -336,7 +337,129 @@ name or a part of a buffer name.  Examples:
 				diff mode (e.g., "file.c.v2")
 
 ==============================================================================
-5. Diff options						*diff-options*
+5. Diff anchors						*diff-anchors*
+
+Diff anchors allow you to control where the diff algorithm aligns and
+synchronize text across files.  Each anchor matches each other in each file,
+allowing you to control the output of a diff.
+
+This is useful when a change involves complicated edits.  For example, if a
+function was moved to another location and further edited.  By default, the
+algorithm aims to create the smallest diff, which results in that entire
+function being considered to be deleted and added on the other side, making it
+hard to see what the actual edit on it was.  You can use diff anchors to pin
+that function so the diff algorithm will align based on it.
+
+To use it, set anchors using 'diffanchors' which is a comma-separated list of
+{address} in each file, and then add "anchor" to 'diffopt'.  Internaly, Vim
+splits each file up into sections split by the anchors.  It performs the diff
+on each pair of sections separately before merging the results back.
+
+Setting 'diffanchors' will update the diff immediately.  If an anchor is tied
+to a mark, and you change what the mark is pointed to, you need to manually
+call |:diffupdate| afterwards to get the updated diff results.
+
+Example:
+
+Let's say we have the following files, side-by-side.  We are interested in the
+change that happened to the function `foo()`, which was both edited and moved.
+
+File A: >
+	int foo() {
+	    int n = 1;
+	    return n;
+	}
+
+	int g = 1;
+
+	int bar(int a) {
+	    a *= 2;
+	    a += 3;
+	    return a;
+	}
+<File B: >
+	int bar(int a) {
+	    a *= 2;
+	    a += 3;
+	    return a;
+	}
+
+	int foo() {
+	    int n = 999;
+	    return n;
+	}
+
+	int g = 1;
+<
+A normal diff will usually align the diff result as such: >
+
+	int foo() {     |----------------
+	    int n = 1;  |----------------
+	    return n;   |----------------
+	}               |----------------
+	                |----------------
+	int g = 1;      |----------------
+	                |----------------
+	int bar(int a) {|int bar(int a) {
+	    a *= 2;     |    a *= 2;
+	    a += 3;     |    a += 3;
+	    return a;   |    return a;
+	}               |}
+	----------------|
+	----------------|int foo() {
+	----------------|    int n = 999;
+	----------------|    return n;
+	----------------|}
+	----------------|
+	----------------|int g = 1;
+<
+What we want is to instead ask the diff to align on `foo()`: >
+
+	----------------|int bar(int a) {
+	----------------|    a *= 2;
+	----------------|    a += 3;
+	----------------|    return a;
+	----------------|}
+	----------------|
+	int foo() {     |int foo() {
+	    int n = 1;  |    int n = 999;
+	    return n;   |    return n;
+	}               |}
+	                |
+	int g = 1;      |int g = 1;
+	                |----------------
+	int bar(int a) {|----------------
+	    a *= 2;     |----------------
+	    a += 3;     |----------------
+	    return a;   |----------------
+	}               |----------------
+<
+
+Below are some ways of setting diff anchors to get the above result.  In each
+example, 'diffopt' needs to have `anchor` set for this to take effect.
+
+Marks: Set the |'a| mark on the `int foo()` lines in each file first before
+setting the anchors: >
+	set diffanchors='a
+
+Pattern: Specify the anchor using a |pattern| (see |:/|).  Here, we make sure
+to always start search from line 1 for consistency: >
+	set diffanchors=1/int\ foo(/
+<
+Selection: Use visual mode to select the entire `foo()` function body in each
+file.  Here, we use two anchors.  This does a better job of making sure only
+the function bodies are anchored against each other but not the lines after
+it.  Note the `'>+1` below.  The "+1" is necessary as we want the split to
+happen below the last line of the function, not above: >
+	set diffanchors='<,'>+1
+<
+Manually set two anchors using line numbers via buffer-local options: >
+	setlocal diffanchors=1,5
+	wincmd w
+	setlocal diffanchors=7,11
+<
+==============================================================================
+6. Diff options						*diff-options*
 
 Also see |'diffopt'| and the "diff" item of |'fillchars'|.