On global citations, URLs and translations

On global citations, URLs and translations

[Miguel Ojeda]

Hi Jonathan, Federico,

While I was writing some new docs for something else, I found that
given that citations are global, some translations are overriding the
normal citations.

For instance, on:

  https://www.kernel.org/doc/html/latest/process/programming-language.html

We have the first link pointing to:

  https://www.kernel.org/doc/html/latest/translations/it_IT/process/programming-language.html#c-language

i.e. the Italian translation; which is clearly not intended. Rather,
it should point to the URL the citation points to.

This may have been my mistake originally, since I wrote the original
file and used citations. Checking now other files around in Docs/, I
see almost nobody uses citations and simply put raw URLs, have a
bottom section on References/Bibliography or use inline hyperlinks.

To be honest, after seeing how citations look in the rendered output,
and given they are global, I think it may be simpler to just use
inline hyperlinks. On the other hand, it is nice to have a common set
of citations (to keep up to date both translations and other
documents). However, if we do this, I guess we need to encourage
people to deal with the Sphinx WARNINGs.

How should we handle this? What should be encouraged for new docs?

Cheers,
Miguel

Re: On global citations, URLs and translations

[Jani Nikula]

On Tue, 12 Nov 2019, Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> wrote:
> Hi Jonathan, Federico,
>
> While I was writing some new docs for something else, I found that
> given that citations are global, some translations are overriding the
> normal citations.
>
> For instance, on:
>
>   https://www.kernel.org/doc/html/latest/process/programming-language.html
>
> We have the first link pointing to:
>
>   https://www.kernel.org/doc/html/latest/translations/it_IT/process/programming-language.html#c-language
>
> i.e. the Italian translation; which is clearly not intended. Rather,
> it should point to the URL the citation points to.
>
> This may have been my mistake originally, since I wrote the original
> file and used citations. Checking now other files around in Docs/, I
> see almost nobody uses citations and simply put raw URLs, have a
> bottom section on References/Bibliography or use inline hyperlinks.
>
> To be honest, after seeing how citations look in the rendered output,
> and given they are global, I think it may be simpler to just use
> inline hyperlinks. On the other hand, it is nice to have a common set
> of citations (to keep up to date both translations and other
> documents). However, if we do this, I guess we need to encourage
> people to deal with the Sphinx WARNINGs.
>
> How should we handle this? What should be encouraged for new docs?

Fix the references in both places to actually make them cross
references. See below.

BR,
Jani.


diff --git a/Documentation/process/programming-language.rst b/Documentation/process/programming-language.rst
index e5f5f065dc24..59efa6d7a053 100644
--- a/Documentation/process/programming-language.rst
+++ b/Documentation/process/programming-language.rst
@@ -3,7 +3,7 @@
 Programming Language
 ====================
 
-The kernel is written in the C programming language [c-language]_.
+The kernel is written in the C programming language `[c-language]`_.
 More precisely, the kernel is typically compiled with ``gcc`` [gcc]_
 under ``-std=gnu89`` [gcc-c-dialect-options]_: the GNU dialect of ISO C90
 (including some C99 features).
@@ -34,7 +34,7 @@ in order to feature detect which ones can be used and/or to shorten the code.
 
 Please refer to ``include/linux/compiler_attributes.h`` for more information.
 
-.. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
+.. _[c-language]: http://www.open-std.org/jtc1/sc22/wg14/www/standards
 .. [gcc] https://gcc.gnu.org
 .. [clang] https://clang.llvm.org
 .. [icc] https://software.intel.com/en-us/c-compilers
diff --git a/Documentation/translations/it_IT/process/programming-language.rst b/Documentation/translations/it_IT/process/programming-language.rst
index f4b006395849..b30661731911 100644
--- a/Documentation/translations/it_IT/process/programming-language.rst
+++ b/Documentation/translations/it_IT/process/programming-language.rst
@@ -8,7 +8,7 @@
 Linguaggio di programmazione
 ============================
 
-Il kernel è scritto nel linguaggio di programmazione C [c-language]_.
+Il kernel è scritto nel linguaggio di programmazione C `[c-language]`_.
 Più precisamente, il kernel viene compilato con ``gcc`` [gcc]_ usando
 l'opzione ``-std=gnu89`` [gcc-c-dialect-options]_: il dialetto GNU
 dello standard ISO C90 (con l'aggiunta di alcune funzionalità da C99)
@@ -41,7 +41,7 @@ possono usare e/o per accorciare il codice.
 Per maggiori informazioni consultate il file d'intestazione
 ``include/linux/compiler_attributes.h``.
 
-.. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
+.. _[c-language]: http://www.open-std.org/jtc1/sc22/wg14/www/standards
 .. [gcc] https://gcc.gnu.org
 .. [clang] https://clang.llvm.org
 .. [icc] https://software.intel.com/en-us/c-compilers



-- 
Jani Nikula, Intel Open Source Graphics Center

Re: On global citations, URLs and translations

[Jonathan Corbet]

On Tue, 12 Nov 2019 16:17:32 +0200
Jani Nikula <jani.nikula@linux.intel.com> wrote:

> Fix the references in both places to actually make them cross
> references. See below.
> 
> BR,
> Jani.
> 
> 
> diff --git a/Documentation/process/programming-language.rst b/Documentation/process/programming-language.rst
> index e5f5f065dc24..59efa6d7a053 100644
> --- a/Documentation/process/programming-language.rst
> +++ b/Documentation/process/programming-language.rst
> @@ -3,7 +3,7 @@
>  Programming Language
>  ====================
>  
> -The kernel is written in the C programming language [c-language]_.
> +The kernel is written in the C programming language `[c-language]`_.
>  More precisely, the kernel is typically compiled with ``gcc`` [gcc]_
>  under ``-std=gnu89`` [gcc-c-dialect-options]_: the GNU dialect of ISO C90
>  (including some C99 features).
> @@ -34,7 +34,7 @@ in order to feature detect which ones can be used and/or to shorten the code.
>  
>  Please refer to ``include/linux/compiler_attributes.h`` for more information.
>  
> -.. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
> +.. _[c-language]: http://www.open-std.org/jtc1/sc22/wg14/www/standards
>  .. [gcc] https://gcc.gnu.org
>  .. [clang] https://clang.llvm.org
>  .. [icc] https://software.intel.com/en-us/c-compilers

That fixes this particular instance, while leaving the adjacent ones
untouched :)

I think this is a good change, especially if applied to all instances.  I
also wonder, though, if we should adopt a rule that translations need
unique labels - prepend "IT-" or some such for the Italian translation,
for example?

Thanks,

jon

Re: On global citations, URLs and translations

[Jani Nikula]

On Tue, 12 Nov 2019, Jonathan Corbet <corbet@lwn.net> wrote:
> On Tue, 12 Nov 2019 16:17:32 +0200
> Jani Nikula <jani.nikula@linux.intel.com> wrote:
>
>> Fix the references in both places to actually make them cross
>> references. See below.
>> 
>> BR,
>> Jani.
>> 
>> 
>> diff --git a/Documentation/process/programming-language.rst b/Documentation/process/programming-language.rst
>> index e5f5f065dc24..59efa6d7a053 100644
>> --- a/Documentation/process/programming-language.rst
>> +++ b/Documentation/process/programming-language.rst
>> @@ -3,7 +3,7 @@
>>  Programming Language
>>  ====================
>>  
>> -The kernel is written in the C programming language [c-language]_.
>> +The kernel is written in the C programming language `[c-language]`_.
>>  More precisely, the kernel is typically compiled with ``gcc`` [gcc]_
>>  under ``-std=gnu89`` [gcc-c-dialect-options]_: the GNU dialect of ISO C90
>>  (including some C99 features).
>> @@ -34,7 +34,7 @@ in order to feature detect which ones can be used and/or to shorten the code.
>>  
>>  Please refer to ``include/linux/compiler_attributes.h`` for more information.
>>  
>> -.. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
>> +.. _[c-language]: http://www.open-std.org/jtc1/sc22/wg14/www/standards
>>  .. [gcc] https://gcc.gnu.org
>>  .. [clang] https://clang.llvm.org
>>  .. [icc] https://software.intel.com/en-us/c-compilers
>
> That fixes this particular instance, while leaving the adjacent ones
> untouched :)

Yeah, that was just a quick hack to prove the point. Perhaps Miguel can
provide the proper patch? ;)

> I think this is a good change, especially if applied to all instances.  I
> also wonder, though, if we should adopt a rule that translations need
> unique labels - prepend "IT-" or some such for the Italian translation,
> for example?

I *think* the references like above (when done properly) are local to
the file. It's the labels that perhaps need this.

Sphinx also has some i18n support which I believe we aren't using, and
it would stand to reason this is covered there. But that probably needs
some dedication from Someone(tm) to figure out.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Graphics Center

Re: On global citations, URLs and translations

[Markus Heiser]

my 2cent ..

I have a doubt that translating has to be a part of the kernel development.

Minimal English is one of the prerequisites to be a part of the community.
Maintainers do not master foreign languages, they are forced to commit
blindly without quality assurance.  APIs will never be translated and
the translation of articles is at random.

   IMO a spin-off might focus on translations.

   -- Markus --

Am 12.11.19 um 16:59 schrieb Jani Nikula:
> On Tue, 12 Nov 2019, Jonathan Corbet <corbet@lwn.net> wrote:
>> On Tue, 12 Nov 2019 16:17:32 +0200
>> Jani Nikula <jani.nikula@linux.intel.com> wrote:
>>
>>> Fix the references in both places to actually make them cross
>>> references. See below.
>>>
>>> BR,
>>> Jani.
>>>
>>>
>>> diff --git a/Documentation/process/programming-language.rst b/Documentation/process/programming-language.rst
>>> index e5f5f065dc24..59efa6d7a053 100644
>>> --- a/Documentation/process/programming-language.rst
>>> +++ b/Documentation/process/programming-language.rst
>>> @@ -3,7 +3,7 @@
>>>   Programming Language
>>>   ====================
>>>   
>>> -The kernel is written in the C programming language [c-language]_.
>>> +The kernel is written in the C programming language `[c-language]`_.
>>>   More precisely, the kernel is typically compiled with ``gcc`` [gcc]_
>>>   under ``-std=gnu89`` [gcc-c-dialect-options]_: the GNU dialect of ISO C90
>>>   (including some C99 features).
>>> @@ -34,7 +34,7 @@ in order to feature detect which ones can be used and/or to shorten the code.
>>>   
>>>   Please refer to ``include/linux/compiler_attributes.h`` for more information.
>>>   
>>> -.. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
>>> +.. _[c-language]: http://www.open-std.org/jtc1/sc22/wg14/www/standards
>>>   .. [gcc] https://gcc.gnu.org
>>>   .. [clang] https://clang.llvm.org
>>>   .. [icc] https://software.intel.com/en-us/c-compilers
>>
>> That fixes this particular instance, while leaving the adjacent ones
>> untouched :)
> 
> Yeah, that was just a quick hack to prove the point. Perhaps Miguel can
> provide the proper patch? ;)
> 
>> I think this is a good change, especially if applied to all instances.  I
>> also wonder, though, if we should adopt a rule that translations need
>> unique labels - prepend "IT-" or some such for the Italian translation,
>> for example?
> 
> I *think* the references like above (when done properly) are local to
> the file. It's the labels that perhaps need this.
> 
> Sphinx also has some i18n support which I believe we aren't using, and
> it would stand to reason this is covered there. But that probably needs
> some dedication from Someone(tm) to figure out.
> 
> BR,
> Jani.
> 
> 

Re: On global citations, URLs and translations

[Federico Vaga]

On 2019-11-13 10:37, Markus Heiser wrote:
> my 2cent ..
> 
> I have a doubt that translating has to be a part of the kernel 
> development.

I have a conflict of interests of course, and because of it I disagree.

> Minimal English is one of the prerequisites to be a part of the 
> community.

In a community there are active members and passive ones. It is true 
that
active members need to know English (it is written in the 
documentation).
But passive members are following the development, they are learning 
from it,
they profit from its openness. For these users English could be a 
problem, or
an imposition; nowadays students future is shaped based on the language 
they
study at school (studying German/French/Italian/Spanish does not open 
the
same doors).

I believe that the Linux kernel and many other open source projects 
should
not just help the industry to cut their costs, but they should also play 
a
social role: education, sharing knowledge. Documentation in general, and
translations as well, are part of this second world.

> Maintainers do not master foreign languages
> they are forced to commit blindly without quality assurance.

In some cases maintainers have been forced to accept code blindly 
without
quality assurance because they do not own the hardware for which they 
are
accepting patches.


> APIs will never be translated and
> the translation of articles is at random.

>   IMO a spin-off might focus on translations.

I may agree on this, only if there is an official place where to put 
them,
like:

https://www.kernel.org/doc/html/zh_CN/latest/

Otherwise, a translation on a random git<whatever> service is useless 
because it does
not have visibility/authority.

>   -- Markus --
> 
> Am 12.11.19 um 16:59 schrieb Jani Nikula:
>> On Tue, 12 Nov 2019, Jonathan Corbet <corbet@lwn.net> wrote:
>>> On Tue, 12 Nov 2019 16:17:32 +0200
>>> Jani Nikula <jani.nikula@linux.intel.com> wrote:
>>> 
>>>> Fix the references in both places to actually make them cross
>>>> references. See below.
>>>> 
>>>> BR,
>>>> Jani.
>>>> 
>>>> 
>>>> diff --git a/Documentation/process/programming-language.rst 
>>>> b/Documentation/process/programming-language.rst
>>>> index e5f5f065dc24..59efa6d7a053 100644
>>>> --- a/Documentation/process/programming-language.rst
>>>> +++ b/Documentation/process/programming-language.rst
>>>> @@ -3,7 +3,7 @@
>>>>   Programming Language
>>>>   ====================
>>>>   -The kernel is written in the C programming language 
>>>> [c-language]_.
>>>> +The kernel is written in the C programming language 
>>>> `[c-language]`_.
>>>>   More precisely, the kernel is typically compiled with ``gcc`` 
>>>> [gcc]_
>>>>   under ``-std=gnu89`` [gcc-c-dialect-options]_: the GNU dialect of 
>>>> ISO C90
>>>>   (including some C99 features).
>>>> @@ -34,7 +34,7 @@ in order to feature detect which ones can be used 
>>>> and/or to shorten the code.
>>>>     Please refer to ``include/linux/compiler_attributes.h`` for more 
>>>> information.
>>>>   -.. [c-language] 
>>>> http://www.open-std.org/jtc1/sc22/wg14/www/standards
>>>> +.. _[c-language]: 
>>>> http://www.open-std.org/jtc1/sc22/wg14/www/standards
>>>>   .. [gcc] https://gcc.gnu.org
>>>>   .. [clang] https://clang.llvm.org
>>>>   .. [icc] https://software.intel.com/en-us/c-compilers
>>> 
>>> That fixes this particular instance, while leaving the adjacent ones
>>> untouched :)
>> 
>> Yeah, that was just a quick hack to prove the point. Perhaps Miguel 
>> can
>> provide the proper patch? ;)
>> 
>>> I think this is a good change, especially if applied to all 
>>> instances.  I
>>> also wonder, though, if we should adopt a rule that translations need
>>> unique labels - prepend "IT-" or some such for the Italian 
>>> translation,
>>> for example?
>> 
>> I *think* the references like above (when done properly) are local to
>> the file. It's the labels that perhaps need this.
>> 
>> Sphinx also has some i18n support which I believe we aren't using, and
>> it would stand to reason this is covered there. But that probably 
>> needs
>> some dedication from Someone(tm) to figure out.
>> 
>> BR,
>> Jani.
>> 
>> 

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

Re: On global citations, URLs and translations

[Jonathan Corbet]

On Wed, 13 Nov 2019 10:37:21 +0100
Markus Heiser <markus.heiser@darmarit.de> wrote:

> I have a doubt that translating has to be a part of the kernel development.
> 
> Minimal English is one of the prerequisites to be a part of the community.
> Maintainers do not master foreign languages, they are forced to commit
> blindly without quality assurance.  APIs will never be translated and
> the translation of articles is at random.

We've had this particular discussion before.  My own feeling is that
translated documentation can make an easier entry point for developers
who did not grow up speaking English; that, in turn, makes our community
just a little bit more inclusive.  We certainly can't *require* any sort
of translation work, but I'm happy to encourage it where the interest
exists.

Thanks,

jon

Re: On global citations, URLs and translations

[Miguel Ojeda]

On Tue, Nov 12, 2019 at 4:59 PM Jani Nikula <jani.nikula@linux.intel.com> wrote:
>
> Sphinx also has some i18n support which I believe we aren't using, and
> it would stand to reason this is covered there. But that probably needs
> some dedication from Someone(tm) to figure out.

The docs say not to go overboard with the reStructuredText markup, so
I am not sure if we should avoid going overboard with Sphinx features
too :)

Cheers,
Miguel

Re: On global citations, URLs and translations

[Federico Vaga]

On 2019-11-14 01:54, Miguel Ojeda wrote:
> On Tue, Nov 12, 2019 at 4:59 PM Jani Nikula 
> <jani.nikula@linux.intel.com> wrote:
>> 
>> Sphinx also has some i18n support which I believe we aren't using, and
>> it would stand to reason this is covered there. But that probably 
>> needs
>> some dedication from Someone(tm) to figure out.
> 
> The docs say not to go overboard with the reStructuredText markup, so
> I am not sure if we should avoid going overboard with Sphinx features
> too :)

In addition, I do not know if it worth the effort of doing i18n in 
Sphinx.
Which problem is going to solve? If we are talking about this mistake, 
it is
a more general mistake, unrelated with translations: a label has been 
used
twice in the documentation. These labels need to become local in the 
document
or replaced with inline links (I prefer this as I already wrote in 
another mail).
A global label "gcc" is likely to give some trouble at some point 
because too
generic.

> Cheers,
> Miguel

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

Re: On global citations, URLs and translations

[Jani Nikula]

On Thu, 14 Nov 2019, Federico Vaga <federico.vaga@vaga.pv.it> wrote:
> On 2019-11-14 01:54, Miguel Ojeda wrote:
>> On Tue, Nov 12, 2019 at 4:59 PM Jani Nikula 
>> <jani.nikula@linux.intel.com> wrote:
>>> 
>>> Sphinx also has some i18n support which I believe we aren't using, and
>>> it would stand to reason this is covered there. But that probably 
>>> needs
>>> some dedication from Someone(tm) to figure out.
>> 
>> The docs say not to go overboard with the reStructuredText markup, so
>> I am not sure if we should avoid going overboard with Sphinx features
>> too :)

We avoid excessive markup to keep the files as readable as possible in
plain text. Adding or using infrastructure does not conflict with this.

> In addition, I do not know if it worth the effort of doing i18n in
> Sphinx.  Which problem is going to solve?

Perhaps making it possible to have the whole English documentation
structure, with certain pages translated to other
languages. Additionally you could have language specific tables of
contents for each language, perhaps automatically generated.

I.e. make the translations more accessible.

> If we are talking about this mistake, it is a more general mistake,
> unrelated with translations: a label has been used twice in the
> documentation. These labels need to become local in the document or
> replaced with inline links (I prefer this as I already wrote in
> another mail).  A global label "gcc" is likely to give some trouble at
> some point because too generic.

They turned into global duplicate labels due to an error in the
hyperlink markup. There is no problem with proper markup.

And tying this back to the beginning, IMHO the named hyperlinks are
*less* of an eyesore than inline markup. Contrast:

	See Foo_.

.. _Foo: http://example.org/what-if-you-have-a-really-long-url

With:

	See `Foo <http://example.org/what-if-you-have-a-really-long-url>`_.

Of course, in this case we also need the backticks in the named targets
because they contain brackets and hyphens; that could be changed
too. Also, you don't have to collect the named targets at the bottom of
the file, you can place them between paragraphs, and it'll be neat in
plain text too.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Graphics Center

Re: On global citations, URLs and translations

[Federico Vaga]

On 2019-11-12 16:42, Jonathan Corbet wrote:
> On Tue, 12 Nov 2019 16:17:32 +0200
> Jani Nikula <jani.nikula@linux.intel.com> wrote:
> 
>> Fix the references in both places to actually make them cross
>> references. See below.
>> 
>> BR,
>> Jani.
>> 
>> 
>> diff --git a/Documentation/process/programming-language.rst 
>> b/Documentation/process/programming-language.rst
>> index e5f5f065dc24..59efa6d7a053 100644
>> --- a/Documentation/process/programming-language.rst
>> +++ b/Documentation/process/programming-language.rst
>> @@ -3,7 +3,7 @@
>>  Programming Language
>>  ====================
>> 
>> -The kernel is written in the C programming language [c-language]_.
>> +The kernel is written in the C programming language `[c-language]`_.
>>  More precisely, the kernel is typically compiled with ``gcc`` [gcc]_
>>  under ``-std=gnu89`` [gcc-c-dialect-options]_: the GNU dialect of ISO 
>> C90
>>  (including some C99 features).
>> @@ -34,7 +34,7 @@ in order to feature detect which ones can be used 
>> and/or to shorten the code.
>> 
>>  Please refer to ``include/linux/compiler_attributes.h`` for more 
>> information.
>> 
>> -.. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
>> +.. _[c-language]: 
>> http://www.open-std.org/jtc1/sc22/wg14/www/standards
>>  .. [gcc] https://gcc.gnu.org
>>  .. [clang] https://clang.llvm.org
>>  .. [icc] https://software.intel.com/en-us/c-compilers
> 
> That fixes this particular instance, while leaving the adjacent ones
> untouched :)
> 
> I think this is a good change, especially if applied to all instances.  
> I
> also wonder, though, if we should adopt a rule that translations need
> unique labels - prepend "IT-" or some such for the Italian translation,
> for example?
> 
> Thanks,
> 
> jon

I personally prefer a full inline reference to external links.

Blah blah blah `BLAH <https://www.blah.blah/>`_

When rendered, we do not care where it is. When we read it from sources 
(IMHO)
it does not look cool but it is nice to have the reference right where 
we talk
about it and not somewhere else in the document: it is there where you 
need it;
it avoids these mistakes, it avoids the need for special labels on 
external links.
For all translated documents I am already using the prefix "it-" on all 
internal
labels.

-- 
Federico Vaga

Re: On global citations, URLs and translations

[Jani Nikula]

On Wed, 13 Nov 2019, Federico Vaga <federico.vaga@vaga.pv.it> wrote:
> On 2019-11-12 16:42, Jonathan Corbet wrote:
>> On Tue, 12 Nov 2019 16:17:32 +0200
>> Jani Nikula <jani.nikula@linux.intel.com> wrote:
>> 
>>> Fix the references in both places to actually make them cross
>>> references. See below.
>>> 
>>> BR,
>>> Jani.
>>> 
>>> 
>>> diff --git a/Documentation/process/programming-language.rst 
>>> b/Documentation/process/programming-language.rst
>>> index e5f5f065dc24..59efa6d7a053 100644
>>> --- a/Documentation/process/programming-language.rst
>>> +++ b/Documentation/process/programming-language.rst
>>> @@ -3,7 +3,7 @@
>>>  Programming Language
>>>  ====================
>>> 
>>> -The kernel is written in the C programming language [c-language]_.
>>> +The kernel is written in the C programming language `[c-language]`_.
>>>  More precisely, the kernel is typically compiled with ``gcc`` [gcc]_
>>>  under ``-std=gnu89`` [gcc-c-dialect-options]_: the GNU dialect of ISO 
>>> C90
>>>  (including some C99 features).
>>> @@ -34,7 +34,7 @@ in order to feature detect which ones can be used 
>>> and/or to shorten the code.
>>> 
>>>  Please refer to ``include/linux/compiler_attributes.h`` for more 
>>> information.
>>> 
>>> -.. [c-language] http://www.open-std.org/jtc1/sc22/wg14/www/standards
>>> +.. _[c-language]: 
>>> http://www.open-std.org/jtc1/sc22/wg14/www/standards
>>>  .. [gcc] https://gcc.gnu.org
>>>  .. [clang] https://clang.llvm.org
>>>  .. [icc] https://software.intel.com/en-us/c-compilers
>> 
>> That fixes this particular instance, while leaving the adjacent ones
>> untouched :)
>> 
>> I think this is a good change, especially if applied to all instances.  
>> I
>> also wonder, though, if we should adopt a rule that translations need
>> unique labels - prepend "IT-" or some such for the Italian translation,
>> for example?
>> 
>> Thanks,
>> 
>> jon
>
> I personally prefer a full inline reference to external links.
>
> Blah blah blah `BLAH <https://www.blah.blah/>`_
>
> When rendered, we do not care where it is. When we read it from
> sources (IMHO) it does not look cool but it is nice to have the
> reference right where we talk about it and not somewhere else in the
> document: it is there where you need it; it avoids these mistakes, it
> avoids the need for special labels on external links.  For all
> translated documents I am already using the prefix "it-" on all
> internal labels.

As I wrote elsewhere, IMO the inline markup is uglier in plain text than
the named targets, which is what we want to avoid. You can place the
named targets right after the paragraph where you use it. And if you
reference the same target more than once, you can reuse the URL and not
have to duplicate.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Graphics Center