Re: On global citations, URLs and translations

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

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