| Message ID | 20200206173040.17337-19-peter.maydell@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Convert QAPI doc comments to generate rST instead of texinfo | expand |
Peter Maydell <peter.maydell@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. > rST doesn't recognize > that markup and emits literal underscores. Switch to *this* instead; > for the texinfo output this will be bold, and for rST it will go back > to being italics. Likewise, *this* doesn't mean italics in rST, it means emphasis. With the Texinfo doc pipeline, the patch changes the markup of this from emphasis to strong. The change will be undone when we switch to rST, where it means emphasis again. > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > --- > qapi/migration.json | 4 ++-- > 1 file changed, 2 insertions(+), 2 deletions(-) > > diff --git a/qapi/migration.json b/qapi/migration.json > index 11033b7a8e6..52f34299698 100644 > --- a/qapi/migration.json > +++ b/qapi/migration.json > @@ -178,8 +178,8 @@ > # expected downtime in milliseconds for the guest in last walk > # of the dirty bitmap. (since 1.3) > # > -# @setup-time: amount of setup time in milliseconds _before_ the > -# iterations begin but _after_ the QMP command is issued. This is designed > +# @setup-time: amount of setup time in milliseconds *before* the > +# iterations begin but *after* the QMP command is issued. This is designed > # to provide an accounting of any activities (such as RDMA pinning) which > # may be expensive, but do not actually occur during the iterative > # migration rounds themselves. (since 1.6) I don't like the commit message, but that's not enough to withhold my Reviewed-by: Markus Armbruster <armbru@redhat.com>
On Fri, 7 Feb 2020 at 16:54, Markus Armbruster <armbru@redhat.com> wrote: > > Peter Maydell <peter.maydell@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. thanks -- PMM
Peter Maydell <peter.maydell@linaro.org> writes: > On Fri, 7 Feb 2020 at 16:54, Markus Armbruster <armbru@redhat.com> wrote: >> >> Peter Maydell <peter.maydell@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 ;)
diff --git a/qapi/migration.json b/qapi/migration.json index 11033b7a8e6..52f34299698 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -178,8 +178,8 @@ # expected downtime in milliseconds for the guest in last walk # of the dirty bitmap. (since 1.3) # -# @setup-time: amount of setup time in milliseconds _before_ the -# iterations begin but _after_ the QMP command is issued. This is designed +# @setup-time: amount of setup time in milliseconds *before* the +# iterations begin but *after* the QMP command is issued. This is designed # to provide an accounting of any activities (such as RDMA pinning) which # may be expensive, but do not actually occur during the iterative # migration rounds themselves. (since 1.6)
The MigrationInfo::setup-time documentation is the only place where we use _this_ inline markup to mean italics. rST doesn't recognize that markup and emits literal underscores. Switch to *this* instead; for the texinfo output this will be bold, and for rST it will go back to being italics. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> --- qapi/migration.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) -- 2.20.1