Re: [PATCH v3] docs/zh_CN: add core-api workqueue.rst translation

From: yanteng si <siyanteng01@gmail.com>
To: Alex Shi <seakeel@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>,
	Yanteng Si <siyanteng@loongson.cn>, Alex Shi <alexs@kernel.org>,
	Huacai Chen <chenhuacai@kernel.org>,
	Jiaxun Yang <jiaxun.yang@flygoat.com>,
	linux-doc@vger.kernel.org, Puyu Wang <realpuyuwang@gmail.com>,
	Wu XiangCheng <bobwxc@email.cn>,
	huangjianghui@uniontech.com
Subject: Re: [PATCH v3] docs/zh_CN: add core-api workqueue.rst translation
Date: Fri, 14 May 2021 17:47:31 +0800	[thread overview]
Message-ID: <CAEensMzfzYasxCjnwR9T7ULa6EW7NWB4Y=nnLP+HX8RLvxiNVQ@mail.gmail.com> (raw)
In-Reply-To: <c91e7f95-0c48-292c-d353-d2ca4ac62051@gmail.com>

Alex Shi <seakeel@gmail.com> 于2021年5月14日周五 下午5:30写道：
>
>
>
> On 2021/5/14 下午5:09, yanteng si wrote:
> > Alex Shi <seakeel@gmail.com> 于2021年5月14日周五 下午12:53写道：
> >>
> >>
> >>
> >> On 2021/5/14 上午12:18, Jonathan Corbet wrote:
> >>>>> This patch translates Documentation/core-api/workqueue.rst into Chinese.
> >>>>>
> >>>>>
> >>>>> Signed-off-by: Yanteng Si <siyanteng@loongson.cn>
> >>>>> Reviewed-by: Alex Shi <alexs@kenrel.org>
> >>>> I fixed that typo too - it appears to originate from Alex...:)
> >>
> >> Sorry for the typo.
> >>
> >>> Actually, I've dropped this back out; it creates vast numbers of
> >>> warnings:
> >>>
> >>>> Documentation/core-api/workqueue:398: ./include/linux/workqueue.h:3: WARNING: Duplicate C declaration, also
> >>>> defined at translations/zh_CN/core-api/workqueue:3.
> >>> This will be the result of the ".. kernel-doc::" directives at the end,
> >>> which create new definitions (within sphinx) for all the symbols pulled
> >>> in.
> >>>
> >>> In the long term, we may want to try to find some sort of fix for this.
> >>> But we're really just recreating a bunch of (English-language)
> >>> documentation that's already rendered once; I'm not sure it makes any
> >>> real sense to do that.  So I would suggest that, for now, when you are
> >>> translating documents with kernel-doc directives, you should leave those
> >>> directives out.  Stick in a note directing readers to the original if
> >>> they want to see that material...
> >>>
> >>> Make sense?
> >>
> >> Yes, it is a reasonable solution for now.
> > OK, I will.
> > I will remove them and then direct the reader to the original
> > document. just like:
> >
> > .. note:: 抱歉，由于原始文档在此处交叉引用了代码中的注释，而现在并不是翻译这些注释的好时机（将会带来很多编译警告），所以请暂时浏览英文文档，链接在本文档顶部。
>
> Jon said just remove kernel-doc, not all line? If so, don't need above explanation.
just like:

 +列表管理函数
 +============
 +
-+.. kernel-doc:: include/linux/list.h
+ include/linux/list.h
 +   :internal:
 +
 +基本的C库函数
 +=============
>_< ?

Thanks,

Yanteng