Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Bagas Sanjaya <bagasdotme@gmail.com>
To:     linux-doc@vger.kernel.org
Cc:     Heiko Carstens <hca@linux.ibm.com>,
        Vasily Gorbik <gor@linux.ibm.com>,
        Alexander Gordeev <agordeev@linux.ibm.com>,
        Christian Borntraeger <borntraeger@linux.ibm.com>,
        Sven Schnelle <svens@linux.ibm.com>,
        Jonathan Corbet <corbet@lwn.net>,
        Halil Pasic <pasic@linux.ibm.com>,
        Tony Krowiak <akrowiak@linux.ibm.com>,
        Jason Herne <jjherne@linux.ibm.com>,
        linux-s390@vger.kernel.org, linux-kernel@vger.kernel.org,
        Bagas Sanjaya <bagasdotme@gmail.com>,
        Stephen Rothwell <sfr@canb.auug.org.au>
Subject: [PATCH 4/8] Documentation: s390: use code blocks for virsh and qemu output
Date:   Fri, 22 Jul 2022 15:49:43 +0700
Message-Id: <20220722084946.22965-5-bagasdotme@gmail.com>
In-Reply-To: <20220722084946.22965-1-bagasdotme@gmail.com>
References: <20220722084946.22965-1-bagasdotme@gmail.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

virsh and qemu output blocks are formatted with definition lists,
however Sphinx isn't happy with the formatting:

Documentation/s390/vfio-ap.rst:998: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/s390/vfio-ap.rst:999: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/s390/vfio-ap.rst:1038: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/s390/vfio-ap.rst:1039: WARNING: Definition list ends without a blank line; unexpected unindent.

Use code blocks instead, which are more appropriate. While at it, also
describe virsh commands where --hmp flag is given.

Link:https://lore.kernel.org/linux-next/20220721205937.10043b5f@canb.auug.org.au/
Fixes: cb269e0aba7c3f ("s390/vfio-ap: update docs to include dynamic config support")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/s390/vfio-ap.rst | 88 ++++++++++++++++++----------------
 1 file changed, 48 insertions(+), 40 deletions(-)

diff --git a/Documentation/s390/vfio-ap.rst b/Documentation/s390/vfio-ap.rst
index c0d76a959ed583..920d67ab7b06ff 100644
--- a/Documentation/s390/vfio-ap.rst
+++ b/Documentation/s390/vfio-ap.rst
@@ -995,70 +995,78 @@ the mdev is in use by a KVM guest. If the guest is being emulated by QEMU,
 its mdev can be hot unplugged from the guest in one of two ways:
 
 1. If the KVM guest was started with libvirt, you can hot unplug the mdev via
-   the following commands:
+   the following commands::
 
       virsh detach-device <guestname> <path-to-device-xml>
 
-      For example, to hot unplug mdev 62177883-f1bb-47f0-914d-32a22e3a8804 from
-      the guest named 'my-guest':
+   For example, to hot unplug mdev 62177883-f1bb-47f0-914d-32a22e3a8804 from
+   the guest named 'my-guest'::
 
-         virsh detach-device my-guest ~/config/my-guest-hostdev.xml
+      virsh detach-device my-guest ~/config/my-guest-hostdev.xml
 
-            The contents of my-guest-hostdev.xml:
+   The contents of my-guest-hostdev.xml:
 
-            <hostdev mode='subsystem' type='mdev' managed='no' model='vfio-ap'>
-              <source>
-                <address uuid='62177883-f1bb-47f0-914d-32a22e3a8804'/>
-              </source>
-            </hostdev>
+      .. code-block:: xml
 
+         <hostdev mode='subsystem' type='mdev' managed='no' model='vfio-ap'>
+           <source>
+             <address uuid='62177883-f1bb-47f0-914d-32a22e3a8804'/>
+           </source>
+         </hostdev>
+
+
+   To hot unplug the vfio_ap mediated device identified on the qemu command
+   line, use::
 
       virsh qemu-monitor-command <guest-name> --hmp "device-del <device-id>"
 
-      For example, to hot unplug the vfio_ap mediated device identified on the
-      qemu command line with 'id=hostdev0' from the guest named 'my-guest':
+   For example, to hot unplug the vfio_ap mediated device identified on the
+   qemu command line with 'id=hostdev0' from the guest named 'my-guest'::
 
-         virsh qemu-monitor-command my-guest --hmp "device_del hostdev0"
+      virsh qemu-monitor-command my-guest --hmp "device_del hostdev0"
 
 2. A vfio_ap mediated device can be hot unplugged by attaching the qemu monitor
-   to the guest and using the following qemu monitor command:
+   to the guest and using the following qemu monitor command::
 
       (QEMU) device-del id=<device-id>
 
-      For example, to hot unplug the vfio_ap mediated device that was specified
-      on the qemu command line with 'id=hostdev0' when the guest was started:
+   For example, to hot unplug the vfio_ap mediated device that was specified
+   on the qemu command line with 'id=hostdev0' when the guest was started::
 
-         (QEMU) device-del id=hostdev0
+      (QEMU) device-del id=hostdev0
 
 After live migration of the KVM guest completes, an AP configuration can be
 restored to the KVM guest by hot plugging a vfio_ap mediated device on the target
 system into the guest in one of two ways:
 
 1. If the KVM guest was started with libvirt, you can hot plug a matrix mediated
-   device into the guest via the following virsh commands:
+   device into the guest via the following virsh commands::
 
-   virsh attach-device <guestname> <path-to-device-xml>
+      virsh attach-device <guestname> <path-to-device-xml>
 
-      For example, to hot plug mdev 62177883-f1bb-47f0-914d-32a22e3a8804 into
-      the guest named 'my-guest':
+   For example, to hot plug mdev 62177883-f1bb-47f0-914d-32a22e3a8804 into
+   the guest named 'my-guest'::
 
-         virsh attach-device my-guest ~/config/my-guest-hostdev.xml
+      virsh attach-device my-guest ~/config/my-guest-hostdev.xml
 
-            The contents of my-guest-hostdev.xml:
+   The contents of my-guest-hostdev.xml:
 
-            <hostdev mode='subsystem' type='mdev' managed='no' model='vfio-ap'>
-              <source>
-                <address uuid='62177883-f1bb-47f0-914d-32a22e3a8804'/>
-              </source>
-            </hostdev>
+   .. code-block:: xml
 
+      <hostdev mode='subsystem' type='mdev' managed='no' model='vfio-ap'>
+           <source>
+             <address uuid='62177883-f1bb-47f0-914d-32a22e3a8804'/>
+           </source>
+      </hostdev>
 
-   virsh qemu-monitor-command <guest-name> --hmp \
-   "device_add vfio-ap,sysfsdev=<path-to-mdev>,id=<device-id>"
+   To hot plug vfio_ap mediated device, use::
 
-      For example, to hot plug the vfio_ap mediated device
-      62177883-f1bb-47f0-914d-32a22e3a8804 into the guest named 'my-guest' with
-      device-id hostdev0:
+      virsh qemu-monitor-command <guest-name> --hmp \
+      "device_add vfio-ap,sysfsdev=<path-to-mdev>,id=<device-id>"
+
+   For example, to hot plug the vfio_ap mediated device
+   ``62177883-f1bb-47f0-914d-32a22e3a8804`` into the guest named 'my-guest'
+   with device-id hostdev0::
 
       virsh qemu-monitor-command my-guest --hmp \
       "device_add vfio-ap,\
@@ -1066,14 +1074,14 @@ system into the guest in one of two ways:
       id=hostdev0"
 
 2. A vfio_ap mediated device can be hot plugged by attaching the qemu monitor
-   to the guest and using the following qemu monitor command:
+   to the guest and using the following qemu monitor command::
 
       (qemu) device_add "vfio-ap,sysfsdev=<path-to-mdev>,id=<device-id>"
 
-      For example, to plug the vfio_ap mediated device
-      62177883-f1bb-47f0-914d-32a22e3a8804 into the guest with the device-id
-      hostdev0:
+   For example, to plug the vfio_ap mediated device
+   ``62177883-f1bb-47f0-914d-32a22e3a8804`` into the guest with the device-id
+   hostdev0::
 
-         (QEMU) device-add "vfio-ap,\
-         sysfsdev=/sys/devices/vfio_ap/matrix/62177883-f1bb-47f0-914d-32a22e3a8804,\
-         id=hostdev0"
+      (QEMU) device-add "vfio-ap,\
+      sysfsdev=/sys/devices/vfio_ap/matrix/62177883-f1bb-47f0-914d-32a22e3a8804,\
+      id=hostdev0"
-- 
An old man doll... just what I always wanted! - Clara