Re: [PATCH 1/3] docs/zh_CN: add core-api kernel-api.rst translation

[Alex Shi <seakeel@gmail.com>]

On 2021/4/30 下午8:34, Matthew Wilcox wrote:
> On Fri, Apr 30, 2021 at 07:06:08PM +0800, Alex Shi wrote:
>> On 2021/4/19 下午9:35, Matthew Wilcox wrote:
>>> and surely you need a '.. kernel-doc' to have the ':internal:' make sense?
>>>
>>> Then, I wonder how useful it is to bring kernel-doc written in English
>>> into a Chinese document?  Wouldn't we be better off admitting that we
>>> don't provide Chinese documentation for kernel APIs and referring to
>>> the English documents?
>>>
>>> (I would love nothing more than to provide Chinese documentation for
>>> kernel APIs, but we don't have any kind of system for providing that
>>> today)
>>>
>>
>> I wouldn't reject the Chinese version of kernel-api, but a bit concern
>> of the subtle of the doc could be kept in translation. It would be a
>> big challenge. :)
> 
> That's a big challenge, to be sure, but logistically, where would we
> keep it?

Hi Willy,

Good question!

I have the same concern with you at the first look. But after check the
translation. I don't feel that bad. Correct Chinese version could be
read much faster and no misleading problem.

> 
> A concrete example, we have:
> 
> Documentation/core-api/xarray.rst
> 
> which has
> .. kernel-doc:: lib/xarray.c

It's a good example, I guess most descriptions in xarray.rst could be
translated for a quick reference.
On other side, Yes there do need a boundary, that would be the
real code, like lib/xarray.c. Guess we'd better stop there.


BTW, 
As to the original/translation version issue, We'd better to written
down the original commit ID in translation commit or doc properly. Then
we know the sync up time.

Thanks
Alex
 
> 
> which contains:
> 
> /**
>  * xas_load() - Load an entry from the XArray (advanced).
>  * @xas: XArray operation state.
>  *
> ...
>  */
> 
> So where do we put the Chinese translations?  The kernel-doc is
> adjacent to the function to "encourage" C programmers to keep
> the documentation up to date when they change the function.
> Do we also put the Chinese text in xarray.c?  Do we have a magic
> Documentation/translations/zh_CN/lib/xarray.c which contains the
> translations of the kernel-doc in lib/xarray.c?  Do we then have tooling
> which notices that the inline documentation in lib/xarray.c has changed
> and notifies the translator to keep it up-to-date?
>