Re: [Qemu-block] [Qemu-devel] [PATCH v3] live-block-ops.txt: Rename, rewrite, and improve it

[John Snow]

On 06/23/2017 04:15 AM, Kashyap Chamarthy wrote:
> On Thu, Jun 22, 2017 at 10:13:03AM -0400, John Snow wrote:
>> On 06/22/2017 04:56 AM, Kashyap Chamarthy wrote:
>>> On Wed, Jun 21, 2017 at 06:49:02PM -0400, John Snow wrote:
> 
> [...]
> 
>>> Yes, I was thinking of this, too -- just link to the 'bitmaps' document.
>>>
>>> A quick side question here: Since upstream QEMU is converging onto
>>> Sphinx, and rST, hope you mind if I convert docs/devel/bitmaps.md into
>>> rST at somepoint, for consistency's sake.  I'll file a separate review,
>>> anyway for that.  In the long term, all / most other documents would
>>> also be converted.
>>>
>>
>> Of course not. I chose bitmaps.md so that it would be nice to view from
>> the github interface while remaining nice to read in plaintext, but feel
>> free to convert it if we actually do standardize on Sphinx/rST.
>>
>> If you can make the generated output look prettier than the github
>> rendering of the markdown I'll ACK it ;)
> 
> :-) Here's a sneak-peak (don't miss the index to your left hand side):
> 
>     
> https://kashyapc.fedorapeople.org/v3-QEMU-Docs/_build/html/docs/bitmaps.html
> 

Looking good, you've got an errant backslash:

'Let’s assume the full backup is named full\_backup.img.'

I also think we should change

"Let’s assume it is named incremental.0.img."

to

"Let's assume the new incremental image is named incremental.0.img"

so as to avoid "it" when dealing with two images.

Otherwise, LGTM.

> Compare that with the GitHub rendering:
> 
>     https://github.com/qemu/qemu/blob/master/docs/devel/bitmaps.md
> 
> And, here's the source (in reStructuredText, despite the ".txt"
> extension) for the 'bitmaps' doc (I made tiny styling changes):
> 
>     
> https://kashyapc.fedorapeople.org/v3-QEMU-Docs/_build/html/_sources/docs/bitmaps.txt
>     
>>> Yes, I fully agree with your suggestion.  I will simply link to the
>>> detailed document you wrote, which I was thinking of anyhow.
>>>
>>> Thanks for your comments!
>>>
>> Sure. You could perhaps mention the different sync modes, including top,
>> none, full and incremental and urge readers to check out the bitmaps
>> document for detailed workings of the incremental mode.
> 
> Yeah, good point.  I'll make that edit in v2.
>