[Qemu-devel] [PATCH] qemu-img: Document --force-share / -U

[Qemu-devel] [PATCH] qemu-img: Document --force-share / -U

[Fam Zheng]

Signed-off-by: Fam Zheng <famz@redhat.com>
---
 qemu-img.texi | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/qemu-img.texi b/qemu-img.texi
index fdcf120f36..3aa63aad55 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -57,6 +57,14 @@ exclusive with the @var{-O} parameters. It is currently required to also use
 the @var{-n} parameter to skip image creation. This restriction may be relaxed
 in a future release.
 
+@item --force-share (-U)
+
+If specified, qemu-img will open the image with shared permissions, which makes
+it less likely to conflict with a running guest's permissions due to image
+locking. For example, this can be used to get the image information (with
+'info' subcommand) when the image is used by a running guest. Note that this
+could produce inconsistent result because of concurrent metadata changes, etc..
+
 @item fmt
 is the disk image format. It is guessed automatically in most cases. See below
 for a description of the supported disk formats.
-- 
2.14.3

Re: [Qemu-devel] [Qemu-block] [PATCH] qemu-img: Document --force-share / -U

[Kashyap Chamarthy]

On Thu, Dec 07, 2017 at 04:44:53PM +0800, Fam Zheng wrote:
> Signed-off-by: Fam Zheng <famz@redhat.com>
> ---
>  qemu-img.texi | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/qemu-img.texi b/qemu-img.texi
> index fdcf120f36..3aa63aad55 100644
> --- a/qemu-img.texi
> +++ b/qemu-img.texi
> @@ -57,6 +57,14 @@ exclusive with the @var{-O} parameters. It is currently required to also use
>  the @var{-n} parameter to skip image creation. This restriction may be relaxed
>  in a future release.
>  
> +@item --force-share (-U)
> +
> +If specified, qemu-img will open the image with shared permissions, which makes

Does 'texi' requires to quote tools like `qemu-img` (or single quotes),
to highlight them in documentation?

> +it less likely to conflict with a running guest's permissions due to image
> +locking. For example, this can be used to get the image information (with
> +'info' subcommand) when the image is used by a running guest. Note that this
> +could produce inconsistent result because of concurrent metadata changes, etc..

Super nit-pick:  an ellipsis[*] is three dots :-), so, when applying you
might want to: s/../.../

[*] https://dictionary.cambridge.org/dictionary/english/ellipsis

Regardless:

Reviewed-by: Kashyap Chamarthy <kchamart@redhat.com>

[...]

-- 
/kashyap

Re: [Qemu-devel] [Qemu-block] [PATCH] qemu-img: Document --force-share / -U

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 1887 bytes --]

On 12/07/2017 04:58 AM, Kashyap Chamarthy wrote:
> On Thu, Dec 07, 2017 at 04:44:53PM +0800, Fam Zheng wrote:
>> Signed-off-by: Fam Zheng <famz@redhat.com>
>> ---
>>  qemu-img.texi | 8 ++++++++
>>  1 file changed, 8 insertions(+)
>>
>> diff --git a/qemu-img.texi b/qemu-img.texi
>> index fdcf120f36..3aa63aad55 100644
>> --- a/qemu-img.texi
>> +++ b/qemu-img.texi
>> @@ -57,6 +57,14 @@ exclusive with the @var{-O} parameters. It is currently required to also use
>>  the @var{-n} parameter to skip image creation. This restriction may be relaxed
>>  in a future release.
>>  
>> +@item --force-share (-U)
>> +
>> +If specified, qemu-img will open the image with shared permissions, which makes
> 
> Does 'texi' requires to quote tools like `qemu-img` (or single quotes),
> to highlight them in documentation?

Our usual markup appears to be:

@code{qemu-img}

> 
>> +it less likely to conflict with a running guest's permissions due to image
>> +locking. For example, this can be used to get the image information (with
>> +'info' subcommand) when the image is used by a running guest. Note that this
>> +could produce inconsistent result because of concurrent metadata changes, etc..
> 
> Super nit-pick:  an ellipsis[*] is three dots :-), so, when applying you
> might want to: s/../.../
> 
> [*] https://dictionary.cambridge.org/dictionary/english/ellipsis

Except that both "etc." and "..." independently convey a sense of
continuation, which means that using both at once is both redundant
(just one will do) and difficult to argue how to typeset (since 'etc.'
is often written with an explicit '.' to emphasize that is an
abbreviation, does that mean you have to write 'etc.''...' for a total
of 4 dots?).

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 619 bytes --]

Re: [Qemu-devel] [Qemu-block] [PATCH] qemu-img: Document --force-share / -U

[Fam Zheng]

On Thu, 12/07 10:53, Eric Blake wrote:
> On 12/07/2017 04:58 AM, Kashyap Chamarthy wrote:
> > On Thu, Dec 07, 2017 at 04:44:53PM +0800, Fam Zheng wrote:
> >> Signed-off-by: Fam Zheng <famz@redhat.com>
> >> ---
> >>  qemu-img.texi | 8 ++++++++
> >>  1 file changed, 8 insertions(+)
> >>
> >> diff --git a/qemu-img.texi b/qemu-img.texi
> >> index fdcf120f36..3aa63aad55 100644
> >> --- a/qemu-img.texi
> >> +++ b/qemu-img.texi
> >> @@ -57,6 +57,14 @@ exclusive with the @var{-O} parameters. It is currently required to also use
> >>  the @var{-n} parameter to skip image creation. This restriction may be relaxed
> >>  in a future release.
> >>  
> >> +@item --force-share (-U)
> >> +
> >> +If specified, qemu-img will open the image with shared permissions, which makes
> > 
> > Does 'texi' requires to quote tools like `qemu-img` (or single quotes),
> > to highlight them in documentation?
> 
> Our usual markup appears to be:
> 
> @code{qemu-img}

Sounds good.

> 
> > 
> >> +it less likely to conflict with a running guest's permissions due to image
> >> +locking. For example, this can be used to get the image information (with
> >> +'info' subcommand) when the image is used by a running guest. Note that this
> >> +could produce inconsistent result because of concurrent metadata changes, etc..
> > 
> > Super nit-pick:  an ellipsis[*] is three dots :-), so, when applying you
> > might want to: s/../.../
> > 
> > [*] https://dictionary.cambridge.org/dictionary/english/ellipsis
> 
> Except that both "etc." and "..." independently convey a sense of
> continuation, which means that using both at once is both redundant
> (just one will do) and difficult to argue how to typeset (since 'etc.'
> is often written with an explicit '.' to emphasize that is an
> abbreviation, does that mean you have to write 'etc.''...' for a total
> of 4 dots?).

I have the impression that "etc." is more correct than "etc" so I used even at
the end of the sensence where there is another period '.', making it "etc..".

If ending the paragraph with "etc." is enough, we can drop one ".".

Fam

Re: [Qemu-devel] [Qemu-block] [PATCH] qemu-img: Document --force-share / -U

[Markus Armbruster]

Fam Zheng <famz@redhat.com> writes:

> On Thu, 12/07 10:53, Eric Blake wrote:
>> On 12/07/2017 04:58 AM, Kashyap Chamarthy wrote:
>> > On Thu, Dec 07, 2017 at 04:44:53PM +0800, Fam Zheng wrote:
[...]
>> >> +it less likely to conflict with a running guest's permissions due to image
>> >> +locking. For example, this can be used to get the image information (with
>> >> +'info' subcommand) when the image is used by a running guest. Note that this
>> >> +could produce inconsistent result because of concurrent metadata changes, etc..
>> > 
>> > Super nit-pick:  an ellipsis[*] is three dots :-), so, when applying you
>> > might want to: s/../.../
>> > 
>> > [*] https://dictionary.cambridge.org/dictionary/english/ellipsis
>> 
>> Except that both "etc." and "..." independently convey a sense of
>> continuation, which means that using both at once is both redundant
>> (just one will do) and difficult to argue how to typeset (since 'etc.'
>> is often written with an explicit '.' to emphasize that is an
>> abbreviation, does that mean you have to write 'etc.''...' for a total
>> of 4 dots?).
>
> I have the impression that "etc." is more correct than "etc"

It is.

>                                                              so I used even at
> the end of the sensence where there is another period '.', making it "etc..".

That's wrong all the same :)

https://en.wikipedia.org/wiki/Period_(punctuation)#Abbreviations

> If ending the paragraph with "etc." is enough, we can drop one ".".

Please do.

Re: [Qemu-devel] [Qemu-block] [PATCH] qemu-img: Document --force-share / -U

[Fam Zheng]

On Fri, 12/08 08:42, Markus Armbruster wrote:
> Fam Zheng <famz@redhat.com> writes:
> 
> > On Thu, 12/07 10:53, Eric Blake wrote:
> >> On 12/07/2017 04:58 AM, Kashyap Chamarthy wrote:
> >> > On Thu, Dec 07, 2017 at 04:44:53PM +0800, Fam Zheng wrote:
> [...]
> >> >> +it less likely to conflict with a running guest's permissions due to image
> >> >> +locking. For example, this can be used to get the image information (with
> >> >> +'info' subcommand) when the image is used by a running guest. Note that this
> >> >> +could produce inconsistent result because of concurrent metadata changes, etc..
> >> > 
> >> > Super nit-pick:  an ellipsis[*] is three dots :-), so, when applying you
> >> > might want to: s/../.../
> >> > 
> >> > [*] https://dictionary.cambridge.org/dictionary/english/ellipsis
> >> 
> >> Except that both "etc." and "..." independently convey a sense of
> >> continuation, which means that using both at once is both redundant
> >> (just one will do) and difficult to argue how to typeset (since 'etc.'
> >> is often written with an explicit '.' to emphasize that is an
> >> abbreviation, does that mean you have to write 'etc.''...' for a total
> >> of 4 dots?).
> >
> > I have the impression that "etc." is more correct than "etc"
> 
> It is.
> 
> >                                                              so I used even at
> > the end of the sensence where there is another period '.', making it "etc..".
> 
> That's wrong all the same :)
> 
> https://en.wikipedia.org/wiki/Period_(punctuation)#Abbreviations
> 
> > If ending the paragraph with "etc." is enough, we can drop one ".".
> 
> Please do.

Yes, thanks, v2 sent.

Fam