Re: [PATCH v3 2/2] qemu-cpu-models.rst: Document -noTSX, mds-no, taa-no, and tsx-ctrl

[Peter Maydell]

On Thu, 20 Feb 2020 at 14:52, Paolo Bonzini <address@hidden> wrote:
> ... refer to Intel's `deep dive into MDS <...>`_.
>
> (I don't know what the trailing underscore is for.

It's because the external-hyperlink syntax is a complication
of the simpler format for within-document references. Inside
a document, you can have a simple link like this:

  This is a link to the target_ defined below.

  .. _target:

  This is where the link target defined above goes to.

So trailing underscore is for words that go to somewhere else,
and leading underscore for words that come from somewhere else.

Syntax complication 1 is that instead of word_ you can
say `some phrase with spaces`_ if you want the link to
span more than one word. (The docutils spec calls these
"phrase-references").

Syntax complication 2 is that instead of having to define
the target of an external URL separately from the place
you wanted to refer to it, like this:

  .. _target: http://somewhere-else.org/

you can directly embed it inside a phrase-reference:

  Go to `somewhere external <http://somewhere-else.org/>`_

which is more convenient if you only wanted to use the URL once.
But the _ is still there because it's still the markup that
indicates "this is going be a link to go somewhere".

> I reaffirm my definition of rST as the Perl of markup formats).

Not going to argue with that :-)  But like Perl, there's
usually some kind of a rationale lurking under the surface.

thanks
-- PMM