Adding a blurb like this was forgotten in 2009.

Signed-off-by: Olaf Hering <olaf@aepfle.de>
---
 docs/formatdomain.rst | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index d4f30bb8af..f07ea34232 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -7079,6 +7079,20 @@ is permitted with the following attributes.
   The audio format, one of ``s8``, ``u8``, ``s16``, ``u16``,
   ``s32``, ``u32``, ``f32``. The default is hypervisor specific.
 
+Note:
+If no ``<audio/>`` element is defined, and the ``graphics`` element is set to
+either 'vnc' or 'sdl', the libvirtd or virtqemud process will honor the following
+environment variables:
+
+* ``SDL_AUDIODRIVER``
+
+  Valid values are 'pulseaudio', 'esd', 'alsa' or 'arts'.
+
+* ``QEMU_AUDIO_DRV``
+
+  Valid values are 'pa', 'pulseaudio', 'none', 'alsa', 'coreaudio', 'jack',
+  'oss', 'sdl', 'spice' or 'file'.
+
 None audio backend
 ^^^^^^^^^^^^^^^^^^
 

On Wed, Jan 12, 2022 at 01:42:00PM +0100, Olaf Hering wrote:
> Adding a blurb like this was forgotten in 2009.

How did you come up with 2009? Not questioning it, just curious :)

> +Note:
> +If no ``<audio/>`` element is defined, and the ``graphics`` element is set to
> +either 'vnc' or 'sdl', the libvirtd or virtqemud process will honor the following
> +environment variables:
> +
> +* ``SDL_AUDIODRIVER``
> +
> +  Valid values are 'pulseaudio', 'esd', 'alsa' or 'arts'.
> +
> +* ``QEMU_AUDIO_DRV``
> +
> +  Valid values are 'pa', 'pulseaudio', 'none', 'alsa', 'coreaudio', 'jack',
> +  'oss', 'sdl', 'spice' or 'file'.

The fact that we accept "pulseaudio" as an alias for "pa" and expect
"file" instead of "wav" are an unfortunate implementation detail and
a bug respectively. I have just posted patches addressing the
latter[1], and I don't think the former should be documented even
though it's technically accepted, especially considering that we're
talking about legacy settings and we want users to use the <audio>
element instead.

For the SDL part, since we don't have to deal with any of the
conversion shenanigans in that case, I would suggest avoiding the
list and using something like

  Valid values are those accepted for the ``driver`` attribute of
  the `SDL audio backend <#sdl-audio-backend>`__.

instead. But your version works fine too if you're keen on keeping
it as is :)


[1] https://listman.redhat.com/archives/libvir-list/2022-January/msg00738.html
-- 
Andrea Bolognani / Red Hat / Virtualization

Mon, 17 Jan 2022 08:09:11 -0800 Andrea Bolognani <abologna@redhat.com>:

> On Wed, Jan 12, 2022 at 01:42:00PM +0100, Olaf Hering wrote:
> > Adding a blurb like this was forgotten in 2009.  
> How did you come up with 2009? Not questioning it, just curious :)

I think the variables and the docs appeared in git at that time.

> But your version works fine too if you're keen on keeping
> it as is :)

I'm fine with whatever unblocks the sysconfig removal.


Olaf

On Mon, Jan 17, 2022 at 05:26:51PM +0100, Olaf Hering wrote:
> Mon, 17 Jan 2022 08:09:11 -0800 Andrea Bolognani <abologna@redhat.com>:
> > But your version works fine too if you're keen on keeping
> > it as is :)
>
> I'm fine with whatever unblocks the sysconfig removal.

I dropped the "pulseaudio" entry, replaced "file" with "wav" and
pushed.

Reviewed-by: Andrea Bolognani <abologna@redhat.com>

-- 
Andrea Bolognani / Red Hat / Virtualization