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? >
