From acab923dce385b8eccb9d4de8fd6b99bfca6628d Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 23 Jan 2020 15:22:40 +0000 Subject: qemu-block-drivers: Convert to rST MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The qemu-block-drivers documentation is currently in docs/qemu-block-drivers.texi in Texinfo format, which we present to the user as: * a qemu-block-drivers manpage * a section of the main qemu-doc HTML documentation Convert the documentation to rST format, and present it to the user as: * a qemu-block-drivers manpage * part of the system/ Sphinx manual This follows the same pattern we've done for qemu-ga and qemu-nbd. We have to drop a cross-reference from the documentation of the -cdrom option back to the qemu-block-drivers documentation, since they're no longer within the same texinfo document. As noted in a comment, the manpage output is slightly compromised due to limitations in Sphinx. In an ideal world, the HTML output would have the various headings like 'Disk image file formats' as top-level section headings (which then appear in the overall system manual's table-of-contents), and it would not have the section headings which make sense only for the manpage like 'synopsis', 'description', and 'see also'. Unfortunately, the mechanism Sphinx provides for restricting pieces of documentation is limited to the point of being flawed: the 'only::' directive is implemented as a filter that is applied at a very late stage in the document processing pipeline, rather than as an early equivalent of an #ifdef. This means that Sphinx's process of identifying which section heading markup styles are which levels of heading gets confused if the 'only::' directive contains section headings which would affect the heading-level of a later heading. I have opted to prioritise making the HTML format look better, with the compromise being that in the manpage the 'Disk image file formats' &c headings are top-level headings rather than being sub-headings under the traditional 'Description' top-level section title. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée Tested-by: Alex Bennée Acked-by: Stefan Hajnoczi Message-id: 20200116141511.16849-4-peter.maydell@linaro.org --- qemu-doc.texi | 12 ------------ 1 file changed, 12 deletions(-) (limited to 'qemu-doc.texi') diff --git a/qemu-doc.texi b/qemu-doc.texi index 617485d146..2328e7ea47 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -633,16 +633,6 @@ encrypted disk images. * disk_images_snapshot_mode:: Snapshot mode * vm_snapshots:: VM snapshots * qemu_img_invocation:: qemu-img Invocation -* disk_images_formats:: Disk image file formats -* host_drives:: Using host drives -* disk_images_fat_images:: Virtual FAT disk images -* disk_images_nbd:: NBD access -* disk_images_sheepdog:: Sheepdog disk images -* disk_images_iscsi:: iSCSI LUNs -* disk_images_gluster:: GlusterFS disk images -* disk_images_ssh:: Secure Shell (ssh) disk images -* disk_images_nvme:: NVMe userspace driver -* disk_image_locking:: Disk image file locking @end menu @node disk_images_quickstart @@ -723,8 +713,6 @@ state is not saved or restored properly (in particular USB). @include qemu-img.texi -@include docs/qemu-block-drivers.texi - @node pcsys_network @section Network emulation -- cgit v1.2.3