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

[Eric Blake]

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 '()'.

> +
> +.. 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.

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>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org

signature.asc
Description: OpenPGP digital signature