Re: [Qemu-block] [PATCH v6 1/2] bitmaps.md: Convert to rST; move it into 'interop' dir

[John Snow]

On 07/10/2017 10:36 PM, Eric Blake wrote:
> On 07/10/2017 03:15 AM, Kashyap Chamarthy wrote:
> > This is part of the on-going effort to convert QEMU upstream
> > documentation syntax to reStructuredText (rST).
> >
> > The conversion to rST was done using:
> >
> >      $ pandoc -f markdown -t rst bitmaps.md -o bitmaps.rst
> >
> > Then, make a couple of small syntactical adjustments.  While at it,
> > reword a statement to avoid ambiguity.  Addressing the feedback from
> > this thread:
> >
> >      https://lists.nongnu.org/archive/html/qemu-devel/2017-06/msg05428.html
> >
> > Signed-off-by: Kashyap Chamarthy <address@hidden>
> > Reviewed-by: John Snow <address@hidden>
> > ---
>
> > ---
> >   docs/devel/bitmaps.md    | 505 ------------------------------------------
> >   docs/interop/bitmaps.rst | 555 +++++++++++++++++++++++++++++++++++++++++++++++
>
> A shame that git rename detection doesn't see these as the same rough
> contents, but not too bad. I'll just review the new text; if I point out
> something that was pre-existing in the old text, it may be nicer to
> split the cleanups into a separate followup patch, but I'm also okay if
> they go in as part of this patch.
>
> My review is less focused on the choices used in representing things in
> rST and on the final display outcome, and more on the text itself
> (grammar and such).
>
> > +++ b/docs/interop/bitmaps.rst
> > +
> > +-  Dirty bitmaps can be created at any time and attached to any node
> > +   (not just complete drives.)
>
> Looks a bit nicer with '.' outside the sub-sentence '()'.

I suppose if I am to be consistent and eschew the double-space following 
a full stop in the name of "It is semantically invalid and serves only 
typesetting purposes," then I should probably also learn to forego my 
typesetter's quotes...

That one is definitely my quirk and not Kashyap's.

> > +
> > +.. contents::
> > +
> > +Dirty Bitmap Names
> > +------------------
> > +
> > +-  A dirty bitmap's name is unique to the node, but bitmaps attached to
> > +   different nodes can share the same name.
> > +
> > +-  Dirty bitmaps created for internal use by QEMU may be anonymous and
> > +   have no name, but any user-created bitmaps may not be. There can be
>
> s/may not be/must have a name/
>
>
> > +
> > +-  This bitmap will have a default granularity that matches the cluster
> > +   size of its associated drive, if available, clamped to between [4KiB,
>
> s/clamped to/clamped/
>
> > +   64KiB]. The current default for qcow2 is 64KiB.
> > +
> > +
>
>
> > +-  QMP example response, highlighting one success and one failure:
> > +
> > +   -  Acknowledgement that the Transaction was accepted and jobs were
> > +      launched:
>
> US spelling prefers Acknowledgment, but I think you are okay because of
> UK spelling.

My judgement again. I've never cared for "acknowledgment" and their ilk. 
I've asked before, but do we officially prefer US or UK spellings?

> Again, since these are probably pre-existing and just code motion, and
> if you've gotten positive review of your use of rST, I'm fine with adding:
>
> Reviewed-by: Eric Blake <address@hidden>

This might be the funniest mail I send all day.

--js