Re: On global citations, URLs and translations

[Jani Nikula <jani.nikula@linux.intel.com>]

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