Re: On global citations, URLs and translations

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

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