[libvirt PATCH] docs: Improve documentation for <serial> and <console>

Users expect to be able to configure the <console> element and see that configuration reflected into the <serial> element or at least sticking, however due to our crazy back-compat code that doesn't always happen. There's really not much we can do to make this kind of corner cases work as the user would expect, especially not without introducing additional complexity in a part of libvirt that already has more than a fair share of it; we can, however, improve the documentation so that it will nudge said users in the right direction. https://bugzilla.redhat.com/show_bug.cgi?id=1770725 Signed-off-by: Andrea Bolognani <abologna(a)redhat.com&gt; --- docs/formatdomain.html.in | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 44e2062d01..5ccf39abd1 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -7510,7 +7510,10 @@ qemu-kvm -net nic,model=? /dev/null <span class="since">since 4.7.0</span>, <code>16550a</code> (usable with the <code>system-serial</code> target type); <code>sclpconsole</code> and <code>sclplmconsole</code> (usable with - the <code>sclp-serial</code> target type). + the <code>sclp-serial</code> target type). Providing a target model is + usually unnecessary: libvirt will automatically pick one that's suitable + for the chosen target type, and overriding that value is generally not + recommended. </p> <p> @@ -7656,7 +7659,8 @@ qemu-kvm -net nic,model=? /dev/null for early boot logging / interactive / recovery use, and one paravirtualized serial console to be used eg. as a side channel. Most people will be fine with having just the first <code>console</code> - element in their configuration. + element in their configuration, but if a specific configuration is + desired then both elements should be specified. </p> <p> -- 2.24.1