Re: [PATCH v3 3/2] qemu-img: Reword 'qemu-img map --output=json' docs
07.07.2021 21:41, Eric Blake wrote: Reword the paragraphs to list the JSON key first, rather than in the middle of prose. Suggested-by: Vladimir Sementsov-Ogievskiy Signed-off-by: Eric Blake Reviewed-by: Vladimir Sementsov-Ogievskiy -- Best regards, Vladimir
Re: [PATCH v3 3/2] qemu-img: Reword 'qemu-img map --output=json' docs
On Wed, Jul 7, 2021 at 9:41 PM Eric Blake wrote: > > Reword the paragraphs to list the JSON key first, rather than in the > middle of prose. > > Suggested-by: Vladimir Sementsov-Ogievskiy > Signed-off-by: Eric Blake > --- > docs/tools/qemu-img.rst | 20 ++-- > 1 file changed, 10 insertions(+), 10 deletions(-) > > diff --git a/docs/tools/qemu-img.rst b/docs/tools/qemu-img.rst > index d6300f7ee03d..1d8470eada0e 100644 > --- a/docs/tools/qemu-img.rst > +++ b/docs/tools/qemu-img.rst > @@ -593,16 +593,16 @@ Command description: >the ``start``, ``length``, ``offset`` fields; >it will also include other more specific information: > > - - whether the sectors contain actual data or not (boolean field ``data``; > -if false, the sectors are either unallocated or stored as optimized > -all-zero clusters); > - - whether the data is known to read as zero (boolean field ``zero``); > - - whether the data is actually present (boolean field ``present``); > -if false, rebasing the backing chain onto a deeper file would pick > -up data from the deeper file; > - - in order to make the output shorter, the target file is expressed as > -a ``depth``; for example, a depth of 2 refers to the backing file > -of the backing file of *FILENAME*. > + - boolean field ``data``: true if the sectors contain actual data, > +false if the sectors are either unallocated or stored as optimized > +all-zero clusters > + - boolean field ``zero``: true if the data is known to read as zero > + - boolean field ``present``: true if the data belongs to the backing > +chain, false if rebasing the backing chain onto a deeper file > +would pick up data from the deeper file; > + - integer field ``depth``: the depth within the backing chain at > +which the data was resolved; for example, a depth of 2 refers to > +the backing file of the backing file of *FILENAME*. > >In JSON format, the ``offset`` field is optional; it is absent in >cases where ``human`` format would omit the entry or exit with an error. > -- > 2.31.1 Would be nice if this could be generated from the json schema instead of repeating the type and description of the fields, but this is a nice improvement. Reviewed-by: Nir Soffer
[PATCH v3 3/2] qemu-img: Reword 'qemu-img map --output=json' docs
Reword the paragraphs to list the JSON key first, rather than in the middle of prose. Suggested-by: Vladimir Sementsov-Ogievskiy Signed-off-by: Eric Blake --- docs/tools/qemu-img.rst | 20 ++-- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/tools/qemu-img.rst b/docs/tools/qemu-img.rst index d6300f7ee03d..1d8470eada0e 100644 --- a/docs/tools/qemu-img.rst +++ b/docs/tools/qemu-img.rst @@ -593,16 +593,16 @@ Command description: the ``start``, ``length``, ``offset`` fields; it will also include other more specific information: - - whether the sectors contain actual data or not (boolean field ``data``; -if false, the sectors are either unallocated or stored as optimized -all-zero clusters); - - whether the data is known to read as zero (boolean field ``zero``); - - whether the data is actually present (boolean field ``present``); -if false, rebasing the backing chain onto a deeper file would pick -up data from the deeper file; - - in order to make the output shorter, the target file is expressed as -a ``depth``; for example, a depth of 2 refers to the backing file -of the backing file of *FILENAME*. + - boolean field ``data``: true if the sectors contain actual data, +false if the sectors are either unallocated or stored as optimized +all-zero clusters + - boolean field ``zero``: true if the data is known to read as zero + - boolean field ``present``: true if the data belongs to the backing +chain, false if rebasing the backing chain onto a deeper file +would pick up data from the deeper file; + - integer field ``depth``: the depth within the backing chain at +which the data was resolved; for example, a depth of 2 refers to +the backing file of the backing file of *FILENAME*. In JSON format, the ``offset`` field is optional; it is absent in cases where ``human`` format would omit the entry or exit with an error. -- 2.31.1