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

Andrea Bolognani 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/20200211144440.186600-1-abologna@redhat.com
docs/formatdomain.html.in | 8 ++++++--
1 file changed, 6 insertions(+), 2 deletions(-)

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

Posted by Andrea Bolognani 2 weeks ago
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@redhat.com>
---
 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

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

Posted by Ján Tomko 2 weeks ago
On Tue, Feb 11, 2020 at 03:44:40PM +0100, Andrea Bolognani wrote:
>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@redhat.com>
>---
> docs/formatdomain.html.in | 8 ++++++--
> 1 file changed, 6 insertions(+), 2 deletions(-)
>

Reviewed-by: Ján Tomko <jtomko@redhat.com>

Jano