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

[Weijie Yuan]

On 2026-09-29 21:10:17 +0800, Chen-Yu Yeh <chenyou910331@xxxxxxxxx> wrote:

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

I actually think the script is getting in the way a bit. Its output is
only meant to serve as a reference, not something that forces us to
constantly worry about how the script behaves. For example, when the
script cannot detect renames, wouldn't it be simpler to just update the
translation as usual? But anyway,

> update to commit d5af79c05e93 ("Documentation: move dev-tools debugging
> files to process/debugging/")
> 
> Signed-off-by: Chen-Yu Yeh <chenyou910331@xxxxxxxxx>

Reviewed-by: Weijie Yuan <wy@xxxxxxxxx>

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