Commit e13c59fa authored by Peter Maydell's avatar Peter Maydell
Browse files

qemu-img: Convert invocation documentation to rST 



The qemu-img documentation is currently in qemu-nbd.texi in Texinfo
format, which we present to the user as:
 * a qemu-img 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-img manpage
 * part of the interop/ Sphinx manual

The qemu-img rST document uses the new hxtool extension
to handle pulling rST fragments out of qemu-img-cmds.hx.

The documentation of the various options and commands is rather
muddled, with some options being described inside the relevant
command description and some in a more general section near the start
of the manual.  All the command synopses are replicated in the .hx
file and then again in the manual.  A lot of text is also duplicated
in the qemu-img.c code for the help text.  I have not attempted to
deal with any of this, but have simply transposed the existing
structure into rST.

As usual, there are some minor formatting changes but no
textual changes, except that as with one or two other conversions
I have dropped the 'see also' section since it's not very
informative and looks odd in the HTML.

Signed-off-by: default avatarPeter Maydell <peter.maydell@linaro.org>
Reviewed-by: default avatarAlex Bennée <alex.bennee@linaro.org>
Tested-by: default avatarAlex Bennée <alex.bennee@linaro.org>
Message-id: 20200124162606.8787-6-peter.maydell@linaro.org
parent 195b5109

MAINTAINERS

+1 −0
Original line number Diff line number Diff line
@@ -1834,6 +1834,7 @@ F: block/ 
F: hw/block/

F: include/block/

F: qemu-img*

F: docs/interop/qemu-img.rst

F: qemu-io*

F: tests/qemu-iotests/

F: util/qemu-progress.c

Makefile

+8 −11
Original line number Diff line number Diff line
@@ -344,7 +344,8 @@ MANUAL_BUILDDIR := docs 
endif



ifdef BUILD_DOCS

DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1

DOCS=qemu-doc.html qemu-doc.txt qemu.1

DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-img.1

DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8

DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8

DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
@@ -744,7 +745,7 @@ rm -f $(MANUAL_BUILDDIR)/$1/objects.inv $(MANUAL_BUILDDIR)/$1/searchindex.js $(M 
endef



distclean: clean

	rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-img-cmds.texi qemu-monitor.texi qemu-monitor-info.texi

	rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi

	rm -f tests/tcg/config-*.mak

	rm -f config-all-devices.mak config-all-disas.mak config.status

	rm -f $(SUBDIR_DEVICES_MAK)
@@ -842,7 +843,7 @@ ifdef CONFIG_POSIX 
	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"

	$(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"

ifeq ($(CONFIG_TOOLS),y)

	$(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1"

	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-img.1 "$(DESTDIR)$(mandir)/man1"

	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"

	$(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"

endif
@@ -1040,7 +1041,7 @@ endef 
$(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel)

	$(call build-manual,devel,html)



$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)

$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_PATH)/qemu-img-cmds.hx

	$(call build-manual,interop,html)



$(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
@@ -1049,7 +1050,7 @@ $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) 
$(MANUAL_BUILDDIR)/system/index.html: $(call manual-deps,system)

	$(call build-manual,system,html)



$(call define-manpage-rule,interop,qemu-ga.8 qemu-nbd.8)

$(call define-manpage-rule,interop,qemu-ga.8 qemu-img.1 qemu-nbd.8,$(SRC_PATH/qemu-img-cmds.hx))



$(call define-manpage-rule,system,qemu-block-drivers.7)
@@ -1067,9 +1068,6 @@ qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx $(SRC_PATH)/scripts/hxtool 
qemu-monitor-info.texi: $(SRC_PATH)/hmp-commands-info.hx $(SRC_PATH)/scripts/hxtool

	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")



qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/scripts/hxtool

	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")



docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi

	@cp -p $< $@
@@ -1078,7 +1076,6 @@ docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi 


qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi

qemu.1: qemu-option-trace.texi

qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi

fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi

docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi

scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi
@@ -1089,9 +1086,9 @@ pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf 
txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt



qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \

	qemu-img.texi qemu-options.texi \

	qemu-options.texi \

	qemu-tech.texi qemu-option-trace.texi \

	qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi \

	qemu-deprecated.texi qemu-monitor.texi \

	qemu-monitor-info.texi \

	docs/qemu-cpu-models.texi docs/security.texi

docs/interop/conf.py

+2 −0
Original line number Diff line number Diff line
@@ -19,6 +19,8 @@ html_theme_options['description'] = u'System Emulation Management and Interopera 
man_pages = [

    ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',

     ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),

    ('qemu-img', 'qemu-img', u'QEMU disk image utility',

     ['Fabrice Bellard'], 1),

    ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',

     ['Anthony Liguori <anthony@codemonkey.ws>'], 8)

]

docs/interop/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -18,6 +18,7 @@ Contents: 
   live-block-operations

   pr-helper

   qemu-ga

   qemu-img

   qemu-nbd

   vhost-user

   vhost-user-gpu

docs/interop/qemu-img.rst

0 → 100644
+825 −0

File added.

Preview size limit exceeded, changes collapsed.