Re: [PATCH 18/29] qapi/migration.json: Replace _this_ with *this*

[Markus Armbruster]

Peter Maydell <address@hidden> writes:

> On Fri, 7 Feb 2020 at 16:54, Markus Armbruster <address@hidden> wrote:
>>
>> Peter Maydell <address@hidden> writes:
>>
>> > The MigrationInfo::setup-time documentation is the only place where
>> > we use _this_ inline markup to mean italics.
>>
>> Nitpick: _this_ does not mean italics, it means emphasis.  See
>> qapi-code-gen.txt section "Documentation markup".  doc.py maps it to
>> @emph{this}, which Texinfo commonly renders in italics when the output
>> format supports that.
>
> Yeah, I know. But to my mind nobody actually cares about "is this
> 'emphasis' or 'strong'", because those are pretty meaningless
> and are not very easy to distinguish semantically. What people
> actually care about is "how does this render", because bold and
> italics look noticeably different and if you're writing you
> might care about which you get. At that point 'strong' is just
> a confusing synonym for 'bold' and 'emphasis' is a confusing
> synonym for 'italics'. But maybe I'm out on a limb here.
>
> Anyway, I'm happy to tweak the commit message.

What about this:

    qapi/migration.json: Replace _this_ with *this*

    The MigrationInfo::setup-time documentation is the only place where
    we use _this_ inline markup for emphasis, commonly rendered in
    italics.  rST doesn't recognize that markup and emits literal
    underscores.

    Switch to *this* instead.  Changes markup to strong emphasis with
    Texinfo, commonly rendered as bold.  With rST, it will go right back
    to emphasis / italics.

I tried to cater both for semantic markup wonks and happy visual
ignorants ;)