Re: [Qemu-block] [PATCH v2 0/2] docs/interop/bitmaps: rewrite and modernize doc

[Vladimir Sementsov-Ogievskiy]

23.04.2019 1:17, John Snow wrote:
> The documentation as written in the 4.0 release is not quite correct as
> of the 4.0 release; though thanks to backwards compatibility it's not
> quite wrong either. It is suitable for inclusion in 4.0.1, or any
> downstream that packages 4.0.
> 
> This patch is an attempt at a nearly full rewrite that revitalizes this
> document to address frequent questions I encounter when discussing the
> API.
> 
> V2:
>    - Split off makefile change into its own little patch.
> 
>    - Addressed (almost) all comments from Vladimir.
>      - Example styling was not reworked.
>    - Renamed all filenames to be consistent throughout the document,
>      fixing a few more file extensions in the process
>    - Reflowed almost all paragraphs to 78 columns for consistency.
>    - Changed a few bulleted lists to paragraphs instead
>    - Changed the big ascii text diagram to a more compact version
>      and clarified its language
>    - While in general I prefer to use en_US spellings, I have
>      replaced "canceled" with "cancelled" so it does not look
>      out of place juxtaposed with BLOCK_JOB_CANCELLED...
> 
> Future work that remains to be done:
> 
> - Paying heed to blockdev-backup workflows
> - Adding a small migration section explaining the options there
> - Possibly reworking some of the sections that all make their own
>    repeated attempts to clarify time interval discretization and adding
>    a proper treatment of the idea start to finish; this may be neccessary
>    to explain the two below items properly:
> - Differential Backups
> - Pull Backups and NBD

This all looks a bit more than just "bitmaps.rst". I think at least most of 
things
about backups should be separated into backup.rst. (But, please, as a 
follow-up, if
you agree).

> 
> John Snow (2):
>    Makefile: add nit-picky mode to sphinx-build
>    docs/interop/bitmaps: rewrite and modernize doc
> 
>   docs/interop/bitmaps.rst | 1600 ++++++++++++++++++++++++++++++--------
>   Makefile                 |    2 +-
>   2 files changed, 1266 insertions(+), 336 deletions(-)
> 


-- 
Best regards,
Vladimir