Peter Maydell <peter.mayd...@linaro.org> writes:
> On Fri, 7 Feb 2020 at 16:54, Markus Armbruster <arm...@redhat.com> wrote:
>>
>> Peter Maydell <peter.mayd...@linaro.org> 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 ;)
