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

[葉宸佑]

On Sat, Oct 03, 2026 at 12:19:30PM +0800, Weijie Yuan wrote:
> 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?

I lean on it more than that, I think. It is the only way we can tell
which translations are behind and by how much -- the scope proposal was
built on its numbers -- and the "update to commit" line is what keeps
those numbers honest. A move without one would make the tool treat the
file as current, and we would lose sight of exactly the files we have
just started tracking.

Where I agree is that this is bookkeeping, not the goal. Updating the
translation as usual is the real fix: whoever does it records the
English commit they synced to, and the rename question goes away. The
rename gap itself is a limitation of the tool, and the better place to
fix it is in checktransupdate.py rather than in notes like this one.

Thanks,
Chen-Yu

Weijie Yuan <wy@xxxxxxxxx> 於 2026年10月3日週六 下午12:19寫道：
>
> 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
> >