Re: On global citations, URLs and translations

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

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