[PATCH 0/4] docs/zh_TW: relocate translations to follow the English layout

[PATCH 0/4] docs/zh_TW: relocate translations to follow the English layout

[Chen-Yu Yeh]

Three zh_TW translations still sit where their English originals used
to live, so tools/docs/checktransupdate.py cannot find the originals at
all.  This series moves them, gives each a baseline, and adds the
:Original: fields that were missing, as proposed in the zh_TW scope
discussion:

  https://lore.kernel.org/linux-doc/CAKspUhJAbCWoxgh2eq8R5g_MiNK=oXgKPUWqGOpHh0w1-Fv74A@mail.gmail.com/

  translation                 moves to                        baseline
  admin-guide/security-bugs   process/security-bugs           44ac5abac86b
  process/magic-number        staging/magic-number            f9a4f4a0e1f5
  dev-tools/gdb-kernel-...    process/debugging/gdb-kernel-.. d5af79c05e93

Each baseline is the English move commit.  checktransupdate.py does not
follow renames, so a commit from before a move is invisible at the new
path and the tool silently falls back to reporting the file as current;
the move commit is the oldest baseline it can use.  Where that hides a
missing change, the commit message records it (6b219431037b for
gdb-kernel-debugging).

Two side effects of the tool reading one "update to commit" line per
commit, which this series does not try to paper over:

 - process/index.rst is touched by the moves and so inherits their
   baseline; the tool now lists five English index commits that the
   recent process series already applied.
 - staging/index.rst and process/debugging/index.rst are new; the latter
   is listed against a592a36e4937, which only drops the index-link
   boilerplate that translations keep anyway.

The fourth relocation named in the proposal, arch/arm/Booting, is one of
the unreachable plain-text files and is removed in a separate series
instead.

This applies on top of v2 of the contact-block cleanup:

  https://lore.kernel.org/linux-doc/20260929115956.229610-1-chenyou910331@gmail.com/

Chen-Yu Yeh (4):
  docs/zh_TW: move security-bugs to process/
  docs/zh_TW: move magic-number to staging/
  docs/zh_TW: move gdb-kernel-debugging to process/debugging/
  docs/zh_TW: add missing :Original: fields

 .../zh_TW/admin-guide/clearing-warn-once.rst  |  2 +
 .../zh_TW/admin-guide/cpu-load.rst            |  2 +
 .../translations/zh_TW/admin-guide/index.rst  |  1 -
 .../translations/zh_TW/arch/index.rst         |  2 +
 .../translations/zh_TW/dev-tools/index.rst    |  1 -
 .../translations/zh_TW/dev-tools/sparse.rst   |  4 +-
 Documentation/translations/zh_TW/index.rst    |  5 +-
 .../debugging}/gdb-kernel-debugging.rst       |  2 +-
 .../zh_TW/process/debugging/index.rst         | 70 +++++++++++++++++++
 .../translations/zh_TW/process/index.rst      |  9 +--
 .../security-bugs.rst                         |  0
 .../translations/zh_TW/staging/index.rst      | 23 ++++++
 .../{process => staging}/magic-number.rst     |  0
 13 files changed, 108 insertions(+), 13 deletions(-)
 rename Documentation/translations/zh_TW/{dev-tools => process/debugging}/gdb-kernel-debugging.rst (99%)
 create mode 100644 Documentation/translations/zh_TW/process/debugging/index.rst
 rename Documentation/translations/zh_TW/{admin-guide => process}/security-bugs.rst (100%)
 create mode 100644 Documentation/translations/zh_TW/staging/index.rst
 rename Documentation/translations/zh_TW/{process => staging}/magic-number.rst (100%)

-- 
2.43.0

[PATCH 1/4] docs/zh_TW: move security-bugs to process/

[Chen-Yu Yeh]

The English original moved from admin-guide/ to process/ in
commit 44ac5abac86b ("Documentation/security-bugs: move from
admin-guide/ to process/"), but the translation stayed behind.
checktransupdate.py locates the English original from the translation's
path, so it currently reports:

  Cannot find the origin path for
  Documentation/translations/zh_TW/admin-guide/security-bugs.rst

Move it to match the English layout, and list it under "Dealing with
bugs" in process/index.rst as the English index does.  The content is
unchanged; its :Original: reference already points at
process/security-bugs and resolves the same way from the new location.

The translation has only had mechanical changes since it was imported in
2021, and the English document did not change between that import and
its move, so the move commit is the English version this translation
mirrors.  It is also the oldest baseline the tool can use:
checktransupdate.py does not follow renames, so a commit from before the
move would make it fall back to comparing dates and report the file as
up to date.

update to commit 44ac5abac86b ("Documentation/security-bugs: move from
admin-guide/ to process/")

Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
 Documentation/translations/zh_TW/admin-guide/index.rst          | 1 -
 Documentation/translations/zh_TW/process/index.rst              | 2 +-
 .../zh_TW/{admin-guide => process}/security-bugs.rst            | 0
 3 files changed, 1 insertion(+), 2 deletions(-)
 rename Documentation/translations/zh_TW/{admin-guide => process}/security-bugs.rst (100%)

diff --git a/Documentation/translations/zh_TW/admin-guide/index.rst b/Documentation/translations/zh_TW/admin-guide/index.rst
index a6e8564ba68f..937f84c69ce9 100644
--- a/Documentation/translations/zh_TW/admin-guide/index.rst
+++ b/Documentation/translations/zh_TW/admin-guide/index.rst
@@ -37,7 +37,6 @@ Todolist:
 
    reporting-issues
    reporting-regressions
-   security-bugs
    bug-hunting
    bug-bisect
    tainted-kernels
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index 30db28078460..18653aa75d7d 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -88,13 +88,13 @@ TODOList:
 .. toctree::
    :maxdepth: 1
 
+   security-bugs
    embargoed-hardware-issues
 
 TODOList:
 
 * debugging/index
 * handling-regressions
-* security-bugs
 * threat-model
 * cve
 
diff --git a/Documentation/translations/zh_TW/admin-guide/security-bugs.rst b/Documentation/translations/zh_TW/process/security-bugs.rst
similarity index 100%
rename from Documentation/translations/zh_TW/admin-guide/security-bugs.rst
rename to Documentation/translations/zh_TW/process/security-bugs.rst
-- 
2.43.0

[PATCH 2/4] docs/zh_TW: move magic-number to staging/

[Chen-Yu Yeh]

The English original moved from process/ to staging/ in
commit f9a4f4a0e1f5 ("Docs: Move magic-number from process to staging"),
but the translation stayed behind.  checktransupdate.py locates the
English original from the translation's path, so it currently reports:

  Cannot find the origin path for
  Documentation/translations/zh_TW/process/magic-number.rst

Move it to match the English layout.  zh_TW has no staging/ directory
yet, so add a staging/index.rst that follows the English one, listing
the documents not translated yet under TODOList as zh_CN does, and link
it from the top-level index in place of its TODOList entry.  The content
of magic-number.rst is unchanged.

Unlike most of the tree, this translation was kept in step for a while
by the English authors themselves: the 2022 series that removed stale
magic numbers edited the translations as well, and so did
commit dd8d4bc28ad7 ("net: remove ax25 and amateur radio (hamradio)
subsystem").  The one English change it lacks is
commit cdcfc029482a ("Documentation: Fix incorrect paths/magic in magic
numbers rst"), which went in after the move.  Use the move commit as the
baseline so that change is reported; checktransupdate.py will also list
dd8d4bc28ad7, which is already reflected here.

update to commit f9a4f4a0e1f5 ("Docs: Move magic-number from process to
staging")

Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
 Documentation/translations/zh_TW/index.rst    |  5 ++--
 .../translations/zh_TW/process/index.rst      |  5 ----
 .../translations/zh_TW/staging/index.rst      | 23 +++++++++++++++++++
 .../{process => staging}/magic-number.rst     |  0
 4 files changed, 26 insertions(+), 7 deletions(-)
 create mode 100644 Documentation/translations/zh_TW/staging/index.rst
 rename Documentation/translations/zh_TW/{process => staging}/magic-number.rst (100%)

diff --git a/Documentation/translations/zh_TW/index.rst b/Documentation/translations/zh_TW/index.rst
index fb86de03c423..1dddf5963864 100644
--- a/Documentation/translations/zh_TW/index.rst
+++ b/Documentation/translations/zh_TW/index.rst
@@ -112,9 +112,10 @@ TODOList:
 有幾份未分類的文檔似乎不適合放在文檔的其他部分，或者可能需要進行一些調整和/或
 轉換爲reStructureText格式，也有可能太舊。
 
-TODOList:
+.. toctree::
+   :maxdepth: 2
 
-* staging/index
+   staging/index
 
 術語表
 ------
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index 18653aa75d7d..de99156324df 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -113,11 +113,6 @@ TODOList:
 
 這裡是一些大多數開發者會感興趣的其他社群指南：
 
-.. toctree::
-   :maxdepth: 1
-
-   magic-number
-
 TODOList:
 
 * kernel-docs
diff --git a/Documentation/translations/zh_TW/staging/index.rst b/Documentation/translations/zh_TW/staging/index.rst
new file mode 100644
index 000000000000..556c63a17f9c
--- /dev/null
+++ b/Documentation/translations/zh_TW/staging/index.rst
@@ -0,0 +1,23 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_TW.rst
+
+:Original: Documentation/staging/index.rst
+
+未分類文件
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   magic-number
+
+TODOList:
+
+* crc32
+* lzo
+* remoteproc
+* rpmsg
+* speculation
+* static-keys
+* xz
diff --git a/Documentation/translations/zh_TW/process/magic-number.rst b/Documentation/translations/zh_TW/staging/magic-number.rst
similarity index 100%
rename from Documentation/translations/zh_TW/process/magic-number.rst
rename to Documentation/translations/zh_TW/staging/magic-number.rst
-- 
2.43.0

[PATCH 3/4] docs/zh_TW: move gdb-kernel-debugging to process/debugging/

[Chen-Yu Yeh]

The English original moved from dev-tools/ to process/debugging/ in
commit d5af79c05e93 ("Documentation: move dev-tools debugging files to
process/debugging/"), but the translation stayed behind.
checktransupdate.py locates the English original from the translation's
path, so it currently reports:

  Cannot find the origin path for
  Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst

Move it to match the English layout, and fix the relative path of the
disclaimer include, which is now one level deeper.  zh_TW has no
process/debugging/ directory yet, so add an index.rst translated from
the English one, listing the guides not translated yet under TODOList,
and link it from process/index.rst in place of its TODOList entry.

The baseline needs a caveat.  The translation lacks
commit 6b219431037b ("docs/scripts/gdb: add necessary make scripts_gdb
step"), which went in before the move, but checktransupdate.py does not
follow renames and cannot report a change made at the old path.  Use the
move commit, the oldest baseline the tool can see, and record the
missing change here instead.  The tool will list
commit 09e1d93a421f ("scripts/gdb: update documentation for
lx_per_cpu"), which already edited this translation, together with the
one later change it really lacks, commit 7f7f468548ce ("Documentation:
Provide hints on how to debug Python GDB scripts").

For the new index.rst the tool will also list
commit a592a36e4937 ("Documentation: use a source-read extension for the
index link boilerplate"); that change only removes the index-link
boilerplate, which this translation does not carry.

update to commit d5af79c05e93 ("Documentation: move dev-tools debugging
files to process/debugging/")

Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
 .../translations/zh_TW/dev-tools/index.rst    |  1 -
 .../debugging}/gdb-kernel-debugging.rst       |  2 +-
 .../zh_TW/process/debugging/index.rst         | 70 +++++++++++++++++++
 .../translations/zh_TW/process/index.rst      |  2 +-
 4 files changed, 72 insertions(+), 3 deletions(-)
 rename Documentation/translations/zh_TW/{dev-tools => process/debugging}/gdb-kernel-debugging.rst (99%)
 create mode 100644 Documentation/translations/zh_TW/process/debugging/index.rst

diff --git a/Documentation/translations/zh_TW/dev-tools/index.rst b/Documentation/translations/zh_TW/dev-tools/index.rst
index 915449762d1a..fafebd092a3d 100644
--- a/Documentation/translations/zh_TW/dev-tools/index.rst
+++ b/Documentation/translations/zh_TW/dev-tools/index.rst
@@ -26,7 +26,6 @@ Documentation/translations/zh_TW/dev-tools/testing-overview.rst
    sparse
    gcov
    kasan
-   gdb-kernel-debugging
 
 Todolist:
 
diff --git a/Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst b/Documentation/translations/zh_TW/process/debugging/gdb-kernel-debugging.rst
similarity index 99%
rename from Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst
rename to Documentation/translations/zh_TW/process/debugging/gdb-kernel-debugging.rst
index 8faa87f26c6a..a9ca1156fea6 100644
--- a/Documentation/translations/zh_TW/dev-tools/gdb-kernel-debugging.rst
+++ b/Documentation/translations/zh_TW/process/debugging/gdb-kernel-debugging.rst
@@ -1,6 +1,6 @@
 .. highlight:: none
 
-.. include:: ../disclaimer-zh_TW.rst
+.. include:: ../../disclaimer-zh_TW.rst
 
 :Original: Documentation/process/debugging/gdb-kernel-debugging.rst
 
diff --git a/Documentation/translations/zh_TW/process/debugging/index.rst b/Documentation/translations/zh_TW/process/debugging/index.rst
new file mode 100644
index 000000000000..4440aa6a97e2
--- /dev/null
+++ b/Documentation/translations/zh_TW/process/debugging/index.rst
@@ -0,0 +1,70 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../../disclaimer-zh_TW.rst
+
+:Original: Documentation/process/debugging/index.rst
+
+============================
+給Linux核心開發者的除錯建議
+============================
+
+一般指南
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   gdb-kernel-debugging
+
+TODOList:
+
+* driver_development_debugging_guide
+* kgdb
+* userspace_debugging_guide
+
+特定子系統指南
+--------------
+
+TODOList:
+
+* media_specific_debugging_guide
+
+一般除錯建議
+============
+
+視問題而定，可用來追蹤問題、甚至用來確認問題是否真的存在的工具也各不相同。
+
+第一步，你必須先弄清楚要除錯的是哪一類問題。根據答案的不同，你的方法與
+工具選擇也可能有所不同。
+
+我是否需要在存取受限的情況下除錯？
+----------------------------------
+
+你對機器的存取是否受到限制，或是無法中斷正在進行的執行？
+
+在這種情況下，你的除錯能力取決於發行版所提供的核心內建的除錯支援。
+Documentation/process/debugging/userspace_debugging_guide.rst 簡要介紹了在
+這種情況下可用的各種除錯工具。在大多數情況下，你可以查看/boot目錄中的
+設定檔，來確認你的核心具備哪些功能。
+
+我是否擁有系統的root存取權限？
+------------------------------
+
+你能否輕易地替換有問題的模組，或安裝新的核心？
+
+若是如此，你可用的工具就多得多，相關工具請參見
+Documentation/process/debugging/driver_development_debugging_guide.rst 。
+
+時序是否是影響因素？
+--------------------
+
+重要的是弄清楚你要除錯的問題是穩定重現（也就是給定一組輸入時，總是得到
+相同的錯誤輸出），還是時有時無。如果問題時有時無，可能有某種時序因素在
+作用。如果在程式碼中插入延遲確實會改變其行為，那麼時序很可能就是其中一個
+因素。
+
+當時序確實會改變程式碼的執行結果時，用簡單的printk()來除錯可能行不通；
+類似的替代方案是使用trace_printk()，它會把除錯訊息記錄到追蹤檔案，而不是
+核心日誌。
+
+**Copyright** ©2024 : Collabora
diff --git a/Documentation/translations/zh_TW/process/index.rst b/Documentation/translations/zh_TW/process/index.rst
index de99156324df..bd638264bbe4 100644
--- a/Documentation/translations/zh_TW/process/index.rst
+++ b/Documentation/translations/zh_TW/process/index.rst
@@ -88,12 +88,12 @@ TODOList:
 .. toctree::
    :maxdepth: 1
 
+   debugging/index
    security-bugs
    embargoed-hardware-issues
 
 TODOList:
 
-* debugging/index
 * handling-regressions
 * threat-model
 * cve
-- 
2.43.0

[PATCH 4/4] docs/zh_TW: add missing :Original: fields

[Chen-Yu Yeh]

Every zh_TW translation names the English document it mirrors in an
:Original: field, except these four.  Add one to each, in the plain path
form that automarkup turns into a link.

dev-tools/sparse.rst still carries the old plain-text header rather than
the disclaimer include, so its field goes at the top of the file.

With this, the only .rst files without the field are index.rst,
disclaimer-zh_TW.rst and glossary.rst, none of which translates an
English document.

Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
---
 .../translations/zh_TW/admin-guide/clearing-warn-once.rst     | 2 ++
 Documentation/translations/zh_TW/admin-guide/cpu-load.rst     | 2 ++
 Documentation/translations/zh_TW/arch/index.rst               | 2 ++
 Documentation/translations/zh_TW/dev-tools/sparse.rst         | 4 +++-
 4 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst b/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst
index 95614600604c..15d54440d224 100644
--- a/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst
+++ b/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst
@@ -2,6 +2,8 @@
 
 .. include:: ../disclaimer-zh_TW.rst
 
+:Original: Documentation/admin-guide/clearing-warn-once.rst
+
 清除 WARN_ONCE
 --------------
 
diff --git a/Documentation/translations/zh_TW/admin-guide/cpu-load.rst b/Documentation/translations/zh_TW/admin-guide/cpu-load.rst
index 20ec5bcd5f18..13f03195ac7e 100644
--- a/Documentation/translations/zh_TW/admin-guide/cpu-load.rst
+++ b/Documentation/translations/zh_TW/admin-guide/cpu-load.rst
@@ -2,6 +2,8 @@
 
 .. include:: ../disclaimer-zh_TW.rst
 
+:Original: Documentation/admin-guide/cpu-load.rst
+
 ========
 CPU 負載
 ========
diff --git a/Documentation/translations/zh_TW/arch/index.rst b/Documentation/translations/zh_TW/arch/index.rst
index 7c0490589465..724468687c20 100644
--- a/Documentation/translations/zh_TW/arch/index.rst
+++ b/Documentation/translations/zh_TW/arch/index.rst
@@ -1,5 +1,7 @@
 .. SPDX-License-Identifier: GPL-2.0
 
+:Original: Documentation/arch/index.rst
+
 處理器體系結構
 ==============
 
diff --git a/Documentation/translations/zh_TW/dev-tools/sparse.rst b/Documentation/translations/zh_TW/dev-tools/sparse.rst
index 7a3487a7b2c7..7ca7fdf6e1e6 100644
--- a/Documentation/translations/zh_TW/dev-tools/sparse.rst
+++ b/Documentation/translations/zh_TW/dev-tools/sparse.rst
@@ -1,4 +1,6 @@
-Chinese translated version of Documentation/dev-tools/sparse.rst
+:Original: Documentation/dev-tools/sparse.rst
+
+Chinese translated version of Documentation/dev-tools/sparse.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
-- 
2.43.0

Re: [PATCH 4/4] docs/zh_TW: add missing :Original: fields

[Jani Nikula]

On Tue, 29 Sep 2026, Chen-Yu Yeh <chenyou910331@gmail.com> wrote:
> Every zh_TW translation names the English document it mirrors in an
> :Original: field, except these four.  Add one to each, in the plain path
> form that automarkup turns into a link.

I'm wondering, are these :Original: fields useful anymore since the
translations extension adds the button to switch between languages?

The pretty much hard-coded expectation is that the English version at
path/to/foo.rst is the original, and its translations are at
translations/xx_YY/path/to/foo.rst.

I.e. neither the HTML nor the RST benefit from it, and it's just
repetition.

BR,
Jani.

>
> dev-tools/sparse.rst still carries the old plain-text header rather than
> the disclaimer include, so its field goes at the top of the file.
>
> With this, the only .rst files without the field are index.rst,
> disclaimer-zh_TW.rst and glossary.rst, none of which translates an
> English document.
>
> Signed-off-by: Chen-Yu Yeh <chenyou910331@gmail.com>
> ---
>  .../translations/zh_TW/admin-guide/clearing-warn-once.rst     | 2 ++
>  Documentation/translations/zh_TW/admin-guide/cpu-load.rst     | 2 ++
>  Documentation/translations/zh_TW/arch/index.rst               | 2 ++
>  Documentation/translations/zh_TW/dev-tools/sparse.rst         | 4 +++-
>  4 files changed, 9 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst b/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst
> index 95614600604c..15d54440d224 100644
> --- a/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst
> +++ b/Documentation/translations/zh_TW/admin-guide/clearing-warn-once.rst
> @@ -2,6 +2,8 @@
>  
>  .. include:: ../disclaimer-zh_TW.rst
>  
> +:Original: Documentation/admin-guide/clearing-warn-once.rst
> +
>  清除 WARN_ONCE
>  --------------
>  
> diff --git a/Documentation/translations/zh_TW/admin-guide/cpu-load.rst b/Documentation/translations/zh_TW/admin-guide/cpu-load.rst
> index 20ec5bcd5f18..13f03195ac7e 100644
> --- a/Documentation/translations/zh_TW/admin-guide/cpu-load.rst
> +++ b/Documentation/translations/zh_TW/admin-guide/cpu-load.rst
> @@ -2,6 +2,8 @@
>  
>  .. include:: ../disclaimer-zh_TW.rst
>  
> +:Original: Documentation/admin-guide/cpu-load.rst
> +
>  ========
>  CPU 負載
>  ========
> diff --git a/Documentation/translations/zh_TW/arch/index.rst b/Documentation/translations/zh_TW/arch/index.rst
> index 7c0490589465..724468687c20 100644
> --- a/Documentation/translations/zh_TW/arch/index.rst
> +++ b/Documentation/translations/zh_TW/arch/index.rst
> @@ -1,5 +1,7 @@
>  .. SPDX-License-Identifier: GPL-2.0
>  
> +:Original: Documentation/arch/index.rst
> +
>  處理器體系結構
>  ==============
>  
> diff --git a/Documentation/translations/zh_TW/dev-tools/sparse.rst b/Documentation/translations/zh_TW/dev-tools/sparse.rst
> index 7a3487a7b2c7..7ca7fdf6e1e6 100644
> --- a/Documentation/translations/zh_TW/dev-tools/sparse.rst
> +++ b/Documentation/translations/zh_TW/dev-tools/sparse.rst
> @@ -1,4 +1,6 @@
> -Chinese translated version of Documentation/dev-tools/sparse.rst
> +:Original: Documentation/dev-tools/sparse.rst
> +
> +Chinese translated version of Documentation/dev-tools/sparse.rst
>  
>  If you have any comment or update to the content, please contact the
>  original document maintainer directly.  However, if you have a problem

-- 
Jani Nikula, Intel