On Thu, 14 Nov 2019, Federico Vaga <federico.vaga@xxxxxxxxxx> wrote: > On 2019-11-14 01:54, Miguel Ojeda wrote: >> On Tue, Nov 12, 2019 at 4:59 PM Jani Nikula >> <jani.nikula@xxxxxxxxxxxxxxx> 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
