Re: [PATCH 03/25] docs/zh_TW: process: sync 4.Coding.rst with the English original

From: 葉宸佑

Date: Thu Nov 19 2026 - 06:51:22 EST


On Thu, Nov 12, 2026 at 01:36:54PM +0800, Weijie Yuan wrote:
> You used <tw_codingstyle> label here, but after rendering, the html
> output is still "Documentation/process/coding-style.rst", which is
> pointing to the zh-tw translation, not the original one. So it is
> inconsistent, right?

You're not misunderstanding, you're right. With :ref:`text <label>`, the
text is displayed as is and only the label decides where the link goes.
Since the label exists, Sphinx has nothing to warn about.

> I suggest that in this series, either use the full path to refer to a
> file directly, or stick to the discouraged writing style and wait until
> once these two series are completed, we can then carry out a thorough
> cleanup. What do you think?

I'll go with the second option for v2: keep the :ref:s and labels, but
display the zh_TW path, e.g.

:ref:`Documentation/translations/zh_TW/process/coding-style.rst
<tw_codingstyle>`

so the text matches where the link goes. Turning them into plain paths
can then go into the cleanup together with the label work.

To make sure nothing is missed, I checked every :ref: in both series
with a script. Besides the ones displaying an English path, it found
one in embargoed-hardware-issues.rst copied from the English text as
"Documentation/admin-guide/ <securitybugs>", where both the text and the
target are English. The zh_TW security-bugs.rst has no label, so I'll
use its full path there instead.

> Regarding the "ref" of one specific section, I remember that it could be
> referred to using a relative path, and with a label?

A :ref: only takes a label, so a section needs one, like
<tw_interleaved_replies> in 2.Process.rst, which points at a section of
submitting-patches.rst. A relative path works with :doc:, but that
links a whole document, and for that a plain path is simpler since
automarkup turns it into a link.

I'll leave your Reviewed-by off this patch in v2.

Thanks for catching this!

Chen-Yu