[libvirt PATCH] docs: Rephrase the video 'none' type to clarify the reasoning

Erik Skultety posted 1 patch 2 weeks ago
Test syntax-check failed
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/libvirt tags/patchew/4c860d9064887e63d5bdfcebc64d733c1da44dbc.1599558996.git.eskultet@redhat.com
docs/formatdomain.rst | 17 ++++++++++-------
1 file changed, 10 insertions(+), 7 deletions(-)

[libvirt PATCH] docs: Rephrase the video 'none' type to clarify the reasoning

Posted by Erik Skultety 2 weeks ago
Signed-off-by: Erik Skultety <eskultet@redhat.com>
---
 docs/formatdomain.rst | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

This is a tiny follow-up improvement resulting from [1] as I felt the paragraph
wasn't clear enough + there were a couple of typographical issues.
[1] https://www.redhat.com/archives/libvir-list/2020-September/msg00329.html

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 1979dfb8d3..cf3ccbecc5 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -5784,13 +5784,16 @@ A video device.
    value "vga", "cirrus", "vmvga", "xen", "vbox", "qxl" ( :since:`since 0.8.6`
    ), "virtio" ( :since:`since 1.3.0` ), "gop" ( :since:`since 3.2.0` ), "bochs"
    ( :since:`since 5.6.0` ), "ramfb" ( :since:`since 5.9.0` ), or "none" (
-   :since:`since 4.6.0` , depending on the hypervisor features available. The
-   purpose of the type ``none`` is to instruct libvirt not to add a default
-   video device in the guest (see the paragraph above). This legacy behaviour
-   can be inconvenient in cases where GPU mediated devices are meant to be the
-   only rendering device within a guest and so specifying another ``video``
-   device along with type ``none``. Refer to Host device assignment to see how
-   to add a mediated device into a guest.
+   :since:`since 4.6.0`) , depending on the hypervisor features available.
+
+   Note: The purpose of the type ``none`` is to instruct libvirt not to add a
+   default video device in the guest (see the ``video`` element description
+   above), since such behaviour is inconvenient in cases where GPU mediated
+   devices are meant to be the only rendering device within a guest. If this
+   is your use case specify a ``none`` type ``video`` device in the XML to stop
+   the default behaviour. Refer to `Host device assignment
+   <#host-device-assignment>`__ to see how to add a mediated device into a
+   guest.

    You can provide the amount of video memory in kibibytes (blocks of 1024
    bytes) using ``vram``. This is supported only for guest type of "vz", "qemu",
--
2.26.2

Re: [libvirt PATCH] docs: Rephrase the video 'none' type to clarify the reasoning

Posted by Michal Privoznik 2 weeks ago
On 9/8/20 11:59 AM, Erik Skultety wrote:
> Signed-off-by: Erik Skultety <eskultet@redhat.com>
> ---
>   docs/formatdomain.rst | 17 ++++++++++-------
>   1 file changed, 10 insertions(+), 7 deletions(-)
> 
> This is a tiny follow-up improvement resulting from [1] as I felt the paragraph
> wasn't clear enough + there were a couple of typographical issues.
> [1] https://www.redhat.com/archives/libvir-list/2020-September/msg00329.html
> 
> diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
> index 1979dfb8d3..cf3ccbecc5 100644
> --- a/docs/formatdomain.rst
> +++ b/docs/formatdomain.rst
> @@ -5784,13 +5784,16 @@ A video device.
>      value "vga", "cirrus", "vmvga", "xen", "vbox", "qxl" ( :since:`since 0.8.6`
>      ), "virtio" ( :since:`since 1.3.0` ), "gop" ( :since:`since 3.2.0` ), "bochs"
>      ( :since:`since 5.6.0` ), "ramfb" ( :since:`since 5.9.0` ), or "none" (
> -   :since:`since 4.6.0` , depending on the hypervisor features available. The
> -   purpose of the type ``none`` is to instruct libvirt not to add a default
> -   video device in the guest (see the paragraph above). This legacy behaviour
> -   can be inconvenient in cases where GPU mediated devices are meant to be the
> -   only rendering device within a guest and so specifying another ``video``
> -   device along with type ``none``. Refer to Host device assignment to see how
> -   to add a mediated device into a guest.
> +   :since:`since 4.6.0`) , depending on the hypervisor features available.

Looks like we like an extra space before ')' in this paragraph.

> +
> +   Note: The purpose of the type ``none`` is to instruct libvirt not to add a
> +   default video device in the guest (see the ``video`` element description
> +   above), since such behaviour is inconvenient in cases where GPU mediated
> +   devices are meant to be the only rendering device within a guest. If this
> +   is your use case specify a ``none`` type ``video`` device in the XML to stop
> +   the default behaviour. Refer to `Host device assignment
> +   <#host-device-assignment>`__ to see how to add a mediated device into a
> +   guest.
> 
>      You can provide the amount of video memory in kibibytes (blocks of 1024
>      bytes) using ``vram``. This is supported only for guest type of "vz", "qemu",


Reviewed-by: Michal Privoznik <mprivozn@redhat.com>

Michal

Re: [libvirt PATCH] docs: Rephrase the video 'none' type to clarify the reasoning

Posted by Ján Tomko 2 weeks ago
On a Tuesday in 2020, Michal Privoznik wrote:
>On 9/8/20 11:59 AM, Erik Skultety wrote:
>>Signed-off-by: Erik Skultety <eskultet@redhat.com>
>>---
>>  docs/formatdomain.rst | 17 ++++++++++-------
>>  1 file changed, 10 insertions(+), 7 deletions(-)
>>
>>This is a tiny follow-up improvement resulting from [1] as I felt the paragraph
>>wasn't clear enough + there were a couple of typographical issues.
>>[1] https://www.redhat.com/archives/libvir-list/2020-September/msg00329.html
>>
>>diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
>>index 1979dfb8d3..cf3ccbecc5 100644
>>--- a/docs/formatdomain.rst
>>+++ b/docs/formatdomain.rst
>>@@ -5784,13 +5784,16 @@ A video device.
>>     value "vga", "cirrus", "vmvga", "xen", "vbox", "qxl" ( :since:`since 0.8.6`
>>     ), "virtio" ( :since:`since 1.3.0` ), "gop" ( :since:`since 3.2.0` ), "bochs"
>>     ( :since:`since 5.6.0` ), "ramfb" ( :since:`since 5.9.0` ), or "none" (
>>-   :since:`since 4.6.0` , depending on the hypervisor features available. The
>>-   purpose of the type ``none`` is to instruct libvirt not to add a default
>>-   video device in the guest (see the paragraph above). This legacy behaviour
>>-   can be inconvenient in cases where GPU mediated devices are meant to be the
>>-   only rendering device within a guest and so specifying another ``video``
>>-   device along with type ``none``. Refer to Host device assignment to see how
>>-   to add a mediated device into a guest.
>>+   :since:`since 4.6.0`) , depending on the hypervisor features available.
>
>Looks like we like an extra space before ')' in this paragraph.
>

That is just the result of the automatic conversion.

The version without spaces in parentheses seems to render just fine for
me, so we can change it.

Jano

>>+
>>+   Note: The purpose of the type ``none`` is to instruct libvirt not to add a
>>+   default video device in the guest (see the ``video`` element description
>>+   above), since such behaviour is inconvenient in cases where GPU mediated
>>+   devices are meant to be the only rendering device within a guest. If this
>>+   is your use case specify a ``none`` type ``video`` device in the XML to stop
>>+   the default behaviour. Refer to `Host device assignment
>>+   <#host-device-assignment>`__ to see how to add a mediated device into a
>>+   guest.
>>
>>     You can provide the amount of video memory in kibibytes (blocks of 1024
>>     bytes) using ``vram``. This is supported only for guest type of "vz", "qemu",
>
>
>Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
>
>Michal
>

Re: [libvirt PATCH] docs: Rephrase the video 'none' type to clarify the reasoning

Posted by Erik Skultety 2 weeks ago
On Tue, Sep 08, 2020 at 01:07:42PM +0200, Ján Tomko wrote:
> On a Tuesday in 2020, Michal Privoznik wrote:
> > On 9/8/20 11:59 AM, Erik Skultety wrote:
> > > Signed-off-by: Erik Skultety <eskultet@redhat.com>
> > > ---
> > >  docs/formatdomain.rst | 17 ++++++++++-------
> > >  1 file changed, 10 insertions(+), 7 deletions(-)
> > >
> > > This is a tiny follow-up improvement resulting from [1] as I felt the paragraph
> > > wasn't clear enough + there were a couple of typographical issues.
> > > [1] https://www.redhat.com/archives/libvir-list/2020-September/msg00329.html
> > >
> > > diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
> > > index 1979dfb8d3..cf3ccbecc5 100644
> > > --- a/docs/formatdomain.rst
> > > +++ b/docs/formatdomain.rst
> > > @@ -5784,13 +5784,16 @@ A video device.
> > >     value "vga", "cirrus", "vmvga", "xen", "vbox", "qxl" ( :since:`since 0.8.6`
> > >     ), "virtio" ( :since:`since 1.3.0` ), "gop" ( :since:`since 3.2.0` ), "bochs"
> > >     ( :since:`since 5.6.0` ), "ramfb" ( :since:`since 5.9.0` ), or "none" (
> > > -   :since:`since 4.6.0` , depending on the hypervisor features available. The
> > > -   purpose of the type ``none`` is to instruct libvirt not to add a default
> > > -   video device in the guest (see the paragraph above). This legacy behaviour
> > > -   can be inconvenient in cases where GPU mediated devices are meant to be the
> > > -   only rendering device within a guest and so specifying another ``video``
> > > -   device along with type ``none``. Refer to Host device assignment to see how
> > > -   to add a mediated device into a guest.
> > > +   :since:`since 4.6.0`) , depending on the hypervisor features available.
> >
> > Looks like we like an extra space before ')' in this paragraph.
> >
>
> That is just the result of the automatic conversion.
>
> The version without spaces in parentheses seems to render just fine for
> me, so we can change it.

Yes, it doesn't matter, but I stayed consistent and pushed it with the space,
like you say, if anyone wants they can send a trivial patch.

Erik