Re: [PATCH 1/2] docs/zh_TW: add process/applying-patches Traditional Chinese translation

[Weijie Yuan]

On Fri, Sep 11, 2026 at 04:50:39PM +0800, 葉宸佑 wrote:
> On Thu, Sep 10, 2026 at 08:18:46PM +0800, Weijie Yuan wrote:
> > > 5. Missing .. _tw_applying_patches: label
> >
> > This kind of top-level label is not recommended/allowed right now ;-)
> 
> You are right, and I checked: doc-guide/sphinx.rst says cross-references
> between documents need no special syntax, just the path. Withdrawn --
> sorry for sending you the wrong way.
> 
> Reading that section also makes my point 6 land differently. The same
> text says:
> 
>   For most use cases, the former is preferred, as it is cleaner and more
>   suited for people reading the source files.  If you come across a
>   :doc: usage that isn't adding any value, please feel free to convert
>   it to just the document path.
> 
> So the two files in 2/2 should converge on README.rst's bare-path form
> rather than howto.rst's :doc:, which is the opposite of what I suggested.

Sure, but I didn't directly carry the concern from the CN side when
sending this series, so now paste it here now (again) for reference. :)

<20260817-apply-patches-v3-0-45e3bd2b1ccc@xxxxxxxxx>:

--- >8 ---

The second patch updates existing zh_CN references to point to the new
translation.  In ordinary paragraphs, the absolute Documentation/...rst
path is used and is handled by automarkup.  The entry in process/howto.rst
is a definition-list term, which automarkup does not process.  It therefore
uses the named :doc: form as the minimal explicit-link exception, without
reintroducing a cn_applying_patches label and using :ref:.

RFC:

I considered the two competing preferences for cross-references. Jon
recommends using a plain absolute Documentation/...rst path, while
another view (I found the discussion in 2021, so I added your email
addresses, thanks.) is to avoid :doc: markup where automarkup can create
the link automatically.  I follow both rules where they apply: the plain
path is used in normal paragraphs.  However, this particular entry is a
definition-list term, which automarkup does not process, so the plain
path is rendered as text rather than a link.  The named :doc: form is
therefore used only for this narrow exception, without adding a
translation-specific label. (Seems to be a workaround)

I would welcome guidance on one stylistic point.  (Since I missed
previous discussions)  The surrounding entries in this definition list
use :ref:, while this new entry uses the named :doc: form because it
links to a whole document without a translation-specific label. Does
this look out of place here?  If so, I am happy to follow the preferred
cross-reference style.

--- >8 ---

And, I think this might be the best way to avoid changing the rendering
method? Although it may seem a bit ugly in terms of the writing style.

(It's been almost a month now. I might need to review my statement to
see if there are any mistakes.) Sorry ;-)

> > It's kind of weird that this series cannot be applied cleanly with
> > Linus' current master tip commit 50d05c7c76c9
> >
> > Did I did something stupid? Confused..
> 
> Nothing stupid -- I hit the same thing trying to apply your series for
> review. Your base includes my process/ series, which Alex picked up on
> 18 August but which has not reached Linus yet, so process/index.rst
> differs between the two trees. It applies on Alex's docs-next.

Oh, that makes sense. It turns out that process/index.rst has been
updated. However, I really should have double-checked instead of posting
it on the list to ask.

> > However, since adding new translations is not our current main goal, I
> > will put this series on the to-do list for now.
> 
> Makes sense -- it will apply cleanly once Alex's pull request lands, so
> there is little to do until then.

Okay.

> > > Would you send that glossary change yourself once v3 lands?
> >
> > I'd like to do that. If you have time, you can do it in person as well.
> > ;-)
> 
> If possible, please make the changes while you're at it; I need to
> prepare the subsequent patch series.

Sure! Appreciate it. ;-)

Thanks!