On Tue, 12 Nov 2019, Miguel Ojeda <miguel.ojeda.sandonis@xxxxxxxxx> 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
