| Message ID | 20200213175647.17628-18-peter.maydell@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Convert QAPI doc comments to generate rST instead of texinfo | expand |
On 2/13/20 6:56 PM, Peter Maydell wrote: > 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. > > rST also uses **this** for strong (commonly rendered bold) where > Texinfo uses *this*. We have one place in the doc comments > which uses strong/bold markup, in qapi/introspect.json: > Note: the QAPI schema is also used to help define *internal* > > When we switch to rST that will be rendered as emphasis / italics. > Markus (who wrote that) thinks that using emphasis / italics > there is an improvement, so we leave that markup alone. > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > Reviewed-by: Markus Armbruster <armbru@redhat.com> > --- > v1->v2: updated commit message. Paras 1 and 2 are from Markus; > paras 3 and 4 are new, and mention a non-change agreed in > the thread off the cover letter of the v1 patch series. > --- > 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) > Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Peter Maydell <peter.maydell@linaro.org> writes: > 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. > > rST also uses **this** for strong (commonly rendered bold) where > Texinfo uses *this*. We have one place in the doc comments > which uses strong/bold markup, in qapi/introspect.json: > Note: the QAPI schema is also used to help define *internal* > > When we switch to rST that will be rendered as emphasis / italics. > Markus (who wrote that) thinks that using emphasis / italics > there is an improvement, so we leave that markup alone. > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > Reviewed-by: Markus Armbruster <armbru@redhat.com> > --- > v1->v2: updated commit message. Paras 1 and 2 are from Markus; > paras 3 and 4 are new, and mention a non-change agreed in > the thread off the cover letter of the v1 patch series. I appreciate your diligent notes here. Thanks! > --- > 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) Reviewed-by: Markus Armbruster <armbru@redhat.com>
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 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. rST also uses **this** for strong (commonly rendered bold) where Texinfo uses *this*. We have one place in the doc comments which uses strong/bold markup, in qapi/introspect.json: Note: the QAPI schema is also used to help define *internal* When we switch to rST that will be rendered as emphasis / italics. Markus (who wrote that) thinks that using emphasis / italics there is an improvement, so we leave that markup alone. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> --- v1->v2: updated commit message. Paras 1 and 2 are from Markus; paras 3 and 4 are new, and mention a non-change agreed in the thread off the cover letter of the v1 patch series. --- qapi/migration.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) -- 2.20.1