[RFC PATCH] doc: translation disclaimer

[RFC PATCH] doc: translation disclaimer

[Federico Vaga]

This is only an example to propose a structure for translation's
disclaimers. The actual text needs some thoughs.

Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
---
 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(-)

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 @@
 Translations
 ============
 
+.. _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`
+- there are not guarantee about translations being in line with the
+  main documentation
+- 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
+
+Translations
+------------
+
 .. toctree::
    :maxdepth: 1
 
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 @@
 :orphan:
 
-.. 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>
-
 .. 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 content 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 @@
 Traduzione italiana
 ===================
 
+.. _it_disclaimer:
+
+Disclaimer
+==========
+The following text should be the translation of :ref:`translations_disclaimer`
+
 L'obiettivo di questa traduzione è di rendere più facile la lettura e
 la comprensione per chi preferisce leggere in lingua italiana.
 Tenete presente che la documentazione di riferimento rimane comunque
-- 
2.20.1

Re: [RFC PATCH] doc: translation disclaimer

[Alex Shi]

Generally It looks good! A short guide to translator is good as well as a disclaimer.


On 2019/3/6 6:06 上午, Federico Vaga wrote:
> This is only an example to propose a structure for translation's
> disclaimers. The actual text needs some thoughs.
>
> Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
> ---
>  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(-)
>
> 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 @@
>  Translations
>  ============
>  
> +.. _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`
Could we merge the 2nd and 3rd into one, like this is not a fork of original file :ref:`xxxx`
> +- there are not guarantee about translations being in line with the
> +  main documentation
Could we merge this one with 1st item, like its purpose is to xxxx without any guarantee of translations ....
> +- 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.

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


> +
> +Translations
> +------------
> +
>  .. toctree::
>     :maxdepth: 1
>  
> 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 @@
>  :orphan:
why the orphan here? does that mean no maintainer for it_IT currently?

Thanks
Alex
>  
> -.. 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>
> -
>  .. 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 content 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 @@
>  Traduzione italiana
>  ===================
>  
> +.. _it_disclaimer:
> +
> +Disclaimer
> +==========
> +The following text should be the translation of :ref:`translations_disclaimer`
> +
>  L'obiettivo di questa traduzione è di rendere più facile la lettura e
>  la comprensione per chi preferisce leggere in lingua italiana.
>  Tenete presente che la documentazione di riferimento rimane comunque

Re: [RFC PATCH] doc: translation disclaimer

[Federico Vaga]

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 上午, Federico Vaga wrote:
> > This is only an example to propose a structure for translation's
> > disclaimers. The actual text needs some thoughs.
> > 
> > Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
> > ---
> > 
> >  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(-)
> > 
> > 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 @@
> > 
> >  Translations
> >  ============
> > 
> > +.. _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`
> 
> Could we merge the 2nd and 3rd into one, like this is not a fork of original
> file :ref:`xxxx`

yes

> > +- there are not guarantee about translations being in line with the
> > +  main documentation
> 
> 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.
> 
> 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 
structure and share the main message.

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

> > +
> > +Translations
> > +------------
> > +
> > 
> >  .. toctree::
> >     :maxdepth: 1
> > 
> > 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 @@
> > 
> >  :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 
exactly the same text in all files, this one is included at the top of all 
translated documents. But, since it is not a real document this is not 
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

> 
> Thanks
> Alex
> 
> > -.. 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>
> > -
> > 
> >  .. 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 content
> > 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 @@
> > 
> >  Traduzione italiana
> >  ===================
> > 
> > +.. _it_disclaimer:
> > +
> > +Disclaimer
> > +==========
> > +The following text should be the translation of
> > :ref:`translations_disclaimer` +
> > 
> >  L'obiettivo di questa traduzione è di rendere più facile la lettura e
> >  la comprensione per chi preferisce leggere in lingua italiana.
> >  Tenete presente che la documentazione di riferimento rimane comunque

Federico Vaga
http://www.federicovaga.it/

Re: [RFC PATCH] doc: translation disclaimer

[Federico Vaga]

On 2019-03-07 05:03, Alex Shi wrote:
> On 2019/3/6 11:17 下午, Federico Vaga wrote:
> 
>> As I wrote in the commit message, this is just a  example to show
>> the
>> structure and share the main message.
>> 
>> What I wrote is just a 10 minutes sketch, to share an idea. This is
>> **not**
>> the text that I'm proposing; what I'm proposing here are the
>> structure and the
>> concepts/ideas/messages. The final patch will be written
>> appropriately, but
>> before doing it I would like to collect the messages that we want to
>> put in
>> it; I listed above what I think is necessary to say.
> 
> Got it. yes, it's a good idea, and we'd better figure out the more
> elegant, precise and legally words. :)

I wouldn't go that far with the legal jargon. There is nothing legal 
about
this, only that who read a translation must be aware of its limitations.


>> +
>> +Translations
>> +------------
>> +
>> 
>> .. toctree::
>> :maxdepth: 1
>> 
>> 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 @@
>> 
>> :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
> exactly the same text in all files, this one is included at the top of
> all
> translated documents. But, since it is not a real document this is not
> 
> 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
> 
>  Thanks a lot for the explanations! :)

-- 
Federico Vaga
http://www.federicovaga.it/