All of lore.kernel.org
 help / color / mirror / Atom feed
From: Matthew Wilcox <willy@infradead.org>
To: Alex Shi <seakeel@gmail.com>
Cc: Yanteng Si <siyanteng@loongson.cn>,
	corbet@lwn.net, alexs@kernel.org, chenhuacai@kernel.org,
	jiaxun.yang@flygoat.com, linux-doc@vger.kernel.org,
	realpuyuwang@gmail.com, bobwxc@email.cn, siyanteng01@gmail.com
Subject: Re: [PATCH 1/3] docs/zh_CN: add core-api kernel-api.rst translation
Date: Fri, 30 Apr 2021 13:34:57 +0100	[thread overview]
Message-ID: <20210430123457.GM1847222@casper.infradead.org> (raw)
In-Reply-To: <77f0e536-9458-5ef2-6cd8-6d47f0452e14@gmail.com>

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?

A concrete example, we have:

Documentation/core-api/xarray.rst

which has
.. kernel-doc:: lib/xarray.c

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?

  reply	other threads:[~2021-04-30 12:36 UTC|newest]

Thread overview: 18+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-04-19 13:10 [PATCH 0/3] add three core api docs Yanteng Si
2021-04-19 13:10 ` [PATCH 1/3] docs/zh_CN: add core-api kernel-api.rst translation Yanteng Si
2021-04-19 13:35   ` Matthew Wilcox
2021-04-19 14:33     ` Wu X.C.
2021-04-30 11:06     ` Alex Shi
2021-04-30 12:34       ` Matthew Wilcox [this message]
2021-04-30 15:05         ` Alex Shi
2021-04-19 13:10 ` [PATCH 2/3] docs/zh_CN: add core-api printk-basics.rst translation Yanteng Si
2021-04-19 16:19   ` Wu X.C.
2021-04-19 13:10 ` [PATCH 3/3] docs/zh_CN: add core-api printk-formats.rst translation Yanteng Si
2021-04-20  5:28   ` Wu X.C.
2021-04-21  7:15     ` teng sterling
2021-04-21  8:11       ` Wu X.C.
2021-04-21  9:54         ` teng sterling
2021-04-23 15:22       ` teng sterling
2021-04-23 16:05         ` Wu X.C.
2021-04-20 22:03 ` [PATCH 0/3] add three core api docs Jonathan Corbet
2021-04-21  1:50   ` teng sterling

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210430123457.GM1847222@casper.infradead.org \
    --to=willy@infradead.org \
    --cc=alexs@kernel.org \
    --cc=bobwxc@email.cn \
    --cc=chenhuacai@kernel.org \
    --cc=corbet@lwn.net \
    --cc=jiaxun.yang@flygoat.com \
    --cc=linux-doc@vger.kernel.org \
    --cc=realpuyuwang@gmail.com \
    --cc=seakeel@gmail.com \
    --cc=siyanteng01@gmail.com \
    --cc=siyanteng@loongson.cn \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.