Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
From:   Federico Vaga <federico.vaga@vaga.pv.it>
To:     Alex Shi <alex.shi@linux.alibaba.com>
Cc:     linux-doc@vger.kernel.org, lkml <linux-kernel@vger.kernel.org>,
        Jonathan Corbet <corbet@lwn.net>, harryxiyou@gmail.com,
        Li Zefan <lizefan@huawei.com>,
        Shawn Guo <shawn.guo@linaro.org>,
        Fengguang Wu <fengguang.wu@intel.com>
Subject: Re: [RFC PATCH] doc: translation disclaimer
Date:   Wed, 06 Mar 2019 16:17:19 +0100
Message-ID: <1683884.6qb0gnyTyR@pcbe13614>
In-Reply-To: <02cb673f-eaf0-f78a-49f3-e95340748694@linux.alibaba.com>
References: <20190305220611.13136-1-federico.vaga@vaga.pv.it> <02cb673f-eaf0-f78a-49f3-e95340748694@linux.alibaba.com>
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain; charset="UTF-8"
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

Hi Alex,

On Wednesday, March 6, 2019 2:57:05 AM CET Alex Shi wrote:
> Generally It looks good! A short guide to translator is good as well as a
> disclaimer.
> On 2019/3/6 6:06 =E4=B8=8A=E5=8D=88, Federico Vaga wrote:
> > This is only an example to propose a structure for translation's
> > disclaimers. The actual text needs some thoughs.
> >=20
> > Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
> > ---
> >=20
> >  Documentation/translations/index.rst           | 18 ++++++++++++++++++
> >  .../translations/it_IT/disclaimer-ita.rst      | 13 +++----------
> >  Documentation/translations/it_IT/index.rst     |  6 ++++++
> >  3 files changed, 27 insertions(+), 10 deletions(-)
> >=20
> > diff --git a/Documentation/translations/index.rst
> > b/Documentation/translations/index.rst index 7f77c52d33aa..b46c8ce98d6e
> > 100644
> > --- a/Documentation/translations/index.rst
> > +++ b/Documentation/translations/index.rst
> > @@ -4,6 +4,24 @@
> >=20
> >  Translations
> >  =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> >=20
> > +.. _translations_disclaimer:
> > +
> > +Disclaimer
> > +----------
> > +Write some text in English here to explain that:
> > +
> > +- its purpose is to ease reading and understanding in other languages
> > +- this is not a fork
> > +- the only official documentation is :ref:`linux_doc`
>=20
> Could we merge the 2nd and 3rd into one, like this is not a fork of origi=
nal
> file :ref:`xxxx`

yes

> > +- there are not guarantee about translations being in line with the
> > +  main documentation
>=20
> Could we merge this one with 1st item, like its purpose is to xxxx without
> any guarantee of translations ....

yes, why not.

I did a list of items to separate the ingredients for the final text.

> > +- translation's maintainer can help people who can't write in English
> > +- only comments and patches about translations are accepted, any other
> > +  discussion about Documentation does not belong here.
>=20
> I am not very good at English. is the following words are bit more clear?
> like, only translation related update are accepted here, contents change
> need goes to original files ...

As I wrote in the commit message, this is just a  example to show the=20
structure and share the main message.

What I wrote is just a 10 minutes sketch, to share an idea. This is **not**=
=20
the text that I'm proposing; what I'm proposing here are the structure and =
the=20
concepts/ideas/messages. The final patch will be written appropriately, but=
=20
before doing it I would like to collect the messages that we want to put in=
=20
it; I listed above what I think is necessary to say.

> > +
> > +Translations
> > +------------
> > +
> >=20
> >  .. toctree::
> >     :maxdepth: 1
> >=20
> > diff --git a/Documentation/translations/it_IT/disclaimer-ita.rst
> > b/Documentation/translations/it_IT/disclaimer-ita.rst index
> > d68e52de6a5d..aacc1a0346db 100644
> > --- a/Documentation/translations/it_IT/disclaimer-ita.rst
> > +++ b/Documentation/translations/it_IT/disclaimer-ita.rst
> > @@ -1,13 +1,6 @@
> >=20
> >  :orphan:
> why the orphan here? does that mean no maintainer for it_IT currently?

It is a Sphinx tag to avoid warnings at build time. Instead of re-writing=20
exactly the same text in all files, this one is included at the top of all=
=20
translated documents. But, since it is not a real document this is not=20
included in any TOC and sphinx complains; that's why we need the orphan tag

http://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html=
#metadata

>=20
> Thanks
> Alex
>=20
> > -.. note::
> > -   This document is maintained by Federico Vaga
> > <federico.vaga@vaga.pv.it>. -   If you find any difference between this
> > document and the original file or a -   problem with the translation,
> > please contact the maintainer of this file. -   Following people helped
> > to translate or review:
> > -   Alessia Mantegazza <amantegazza@vaga.pv.it>
> > -
> >=20
> >  .. warning::
> > -   The purpose of this file is to be easier to read and understand for
> > Italian -   speakers and is not intended as a fork. So, if you have any
> > comments or -   updates for this file please try to update the original
> > English file first. +   Short (to not pollute the document) text in
> > Italian to explain that for any +   doubt about the documentation conte=
nt
> > people should refer to the English +   documentation. Read the
> > :ref:`it_disclaimer`.
> > diff --git a/Documentation/translations/it_IT/index.rst
> > b/Documentation/translations/it_IT/index.rst index
> > ea9b2916b3e4..4b0b3da97c73 100644
> > --- a/Documentation/translations/it_IT/index.rst
> > +++ b/Documentation/translations/it_IT/index.rst
> > @@ -4,6 +4,12 @@
> >=20
> >  Traduzione italiana
> >  =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> >=20
> > +.. _it_disclaimer:
> > +
> > +Disclaimer
> > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
> > +The following text should be the translation of
> > :ref:`translations_disclaimer` +
> >=20
> >  L'obiettivo di questa traduzione =C3=A8 di rendere pi=C3=B9 facile la =
lettura e
> >  la comprensione per chi preferisce leggere in lingua italiana.
> >  Tenete presente che la documentazione di riferimento rimane comunque

=46ederico Vaga
http://www.federicovaga.it/