Hi On Fri, Nov 18, 2016 at 4:32 PM Markus Armbruster <arm...@redhat.com> wrote:
> Marc-André Lureau <marcandre.lur...@redhat.com> writes: > > > Generate and install the man and html version of QAPI documentation. > > > > Add it also to optional pdf/dvi/info targets. > > > > Also support plain-text targets docs/qemu-ga-ref.txt & > docs/qemu-qmp-ref.txt. > > > > Signed-off-by: Marc-André Lureau <marcandre.lur...@redhat.com> > > --- > > Makefile | 56 > +++++++++++++++++++++++++++++++++++++++++++++++------- > > .gitignore | 11 ++++++++++- > > docs/qmp-intro.txt | 3 +-- > > 3 files changed, 60 insertions(+), 10 deletions(-) > > > > diff --git a/Makefile b/Makefile > > index 3617736..cc1c46e 100644 > > --- a/Makefile > > +++ b/Makefile > > @@ -91,6 +91,8 @@ HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF) > > > > ifdef BUILD_DOCS > > DOCS=qemu-doc.html qemu.1 qemu-img.1 qemu-nbd.8 qemu-ga.8 > > +DOCS+=docs/qemu-qmp-ref.html docs/qemu-qmp-ref.7 > > +DOCS+=docs/qemu-ga-ref.html docs/qemu-ga-ref.7 > > ifdef CONFIG_VIRTFS > > DOCS+=fsdev/virtfs-proxy-helper.1 > > endif > > @@ -266,6 +268,7 @@ qemu-ga$(EXESUF): QEMU_CFLAGS += -I > qga/qapi-generated > > gen-out-type = $(subst .,-,$(suffix $@)) > > > > qapi-py = $(SRC_PATH)/scripts/qapi.py $(SRC_PATH)/scripts/ordereddict.py > > +qapi-py += $(SRC_PATH)/scripts/qapi2texi.py > > > > qga/qapi-generated/qga-qapi-types.c qga/qapi-generated/qga-qapi-types.h > :\ > > $(SRC_PATH)/qga/qapi-schema.json $(SRC_PATH)/scripts/qapi-types.py > $(qapi-py) > > @@ -395,6 +398,11 @@ distclean: clean > > rm -f qemu-doc.vr > > rm -f config.log > > rm -f linux-headers/asm > > + rm -f qemu-ga-qapi.texi qemu-qapi.texi > > + rm -f docs/qemu-qmp-ref.7 docs/qemu-ga-ref.7 > > + rm -f docs/qemu-qmp-ref.txt docs/qemu-ga-ref.txt > > + rm -f docs/qemu-qmp-ref.pdf docs/qemu-ga-ref.pdf > > + rm -f docs/qemu-qmp-ref.html docs/qemu-ga-ref.html > > Missing: .dvi > I dropped it in a previous patch in the new series > > > for d in $(TARGET_DIRS); do \ > > rm -rf $$d || exit 1 ; \ > > done > > @@ -431,9 +439,12 @@ endif > > install-doc: $(DOCS) > > $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)" > > $(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)" > > + $(INSTALL_DATA) docs/qemu-qmp-ref.html "$(DESTDIR)$(qemu_docdir)" > > Personally, I'd install .txt along with .html, because the .txt is > perfectly legible, and plain text is easier to read in some situations. > We don't do that for qemu-doc, though. > Ok, let's install them all > > > ifdef CONFIG_POSIX > > $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1" > > $(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1" > > + $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7" > > + $(INSTALL_DATA) docs/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7" > > ifneq ($(TOOLS),) > > $(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1" > > $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8" > > @@ -441,6 +452,8 @@ ifneq ($(TOOLS),) > > endif > > ifneq (,$(findstring qemu-ga,$(TOOLS))) > > $(INSTALL_DATA) qemu-ga.8 "$(DESTDIR)$(mandir)/man8" > > + $(INSTALL_DATA) docs/qemu-ga-ref.html "$(DESTDIR)$(qemu_docdir)" > > + $(INSTALL_DATA) docs/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7" > > endif > > endif > > ifdef CONFIG_VIRTFS > > @@ -528,9 +541,9 @@ ui/console-gl.o: $(SRC_PATH)/ui/console-gl.c \ > > ui/shader/texture-blit-vert.h ui/shader/texture-blit-frag.h > > > > # documentation > > -MAKEINFO=makeinfo > > +MAKEINFO=makeinfo -D 'VERSION $(VERSION)' > > MAKEINFOFLAGS=--no-headers --no-split --number-sections > > -TEXIFLAG=$(if $(V),,--quiet) > > +TEXIFLAG=$(if $(V),,--quiet) --command='@set VERSION $(VERSION)' > > %.dvi: %.texi > > $(call quiet-command,texi2dvi $(TEXIFLAG) -I . $<,"GEN","$@") > > > > Defines variable VERSION for all .texi, not just qemu-*-ref.texi, for > simplicity. Works for me. > > > @@ -542,7 +555,11 @@ TEXIFLAG=$(if $(V),,--quiet) > > $(call quiet-command,$(MAKEINFO) $< -o $@,"GEN","$@") > > > > %.pdf: %.texi > > - $(call quiet-command,texi2pdf $(TEXIFLAG) -I . $<,"GEN","$@") > > + $(call quiet-command,texi2pdf $(TEXIFLAG) -I . $< -o $@,"GEN","$@") > > I guess this simply makes the default implicit. Okay. > > > + > > +%.txt: %.texi > > + $(call quiet-command,LC_ALL=C $(MAKEINFO) $(MAKEINFOFLAGS) > --plaintext $< -o $@,\ > > + " GEN $@") > > $ make docs/qemu-qmp-ref.txt > GEN docs/qemu-qmp-ref.txt > Negative repeat count does nothing at > /usr/share/texinfo/Texinfo/Convert/Line.pm line 128. > Negative repeat count does nothing at > /usr/share/texinfo/Texinfo/Convert/Line.pm line 128. > Negative repeat count does nothing at > /usr/share/texinfo/Texinfo/Convert/Line.pm line 128. > > Could be something wrong with my system. The result looks okay to me > all the same. > I have the same warning, seems to be harmless though... > > > > > qemu-options.texi: $(SRC_PATH)/qemu-options.hx > $(SRC_PATH)/scripts/hxtool > > $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > > $@,"GEN","$@") > > @@ -556,6 +573,12 @@ qemu-monitor-info.texi: > $(SRC_PATH)/hmp-commands-info.hx $(SRC_PATH)/scripts/hxt > > qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx > $(SRC_PATH)/scripts/hxtool > > $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > > $@,"GEN","$@") > > > > +qemu-qapi.texi: $(qapi-modules) $(qapi-py) > > + $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi2texi.py $< > > $@,"GEN" "$@") > > + > > +qemu-ga-qapi.texi: $(SRC_PATH)/qga/qapi-schema.json $(qapi-py) > > + $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi2texi.py $< > > $@,"GEN","$@") > > + > > qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi > qemu-monitor-info.texi > > $(call quiet-command, \ > > perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu.pod && \ > > @@ -587,16 +610,35 @@ qemu-ga.8: qemu-ga.texi > > $(POD2MAN) --section=8 --center=" " --release=" " qemu-ga.pod > > $@, \ > > "GEN","$@") > > > > -dvi: qemu-doc.dvi > > -html: qemu-doc.html > > -info: qemu-doc.info > > -pdf: qemu-doc.pdf > > +docs/qemu-qmp-ref.7: > > + $(call quiet-command, \ > > + perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu-qmp-ref.pod > && \ > > + $(POD2MAN) --section=7 --center=" " --release=" " > qemu-qmp-ref.pod > $@, \ > > + "GEN","$@") > > + > > +docs/qemu-ga-ref.7: > > + $(call quiet-command, \ > > + perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< qemu-ga-ref.pod > && \ > > + $(POD2MAN) --section=7 --center=" " --release=" " qemu-ga-ref.pod > > $@, \ > > + "GEN","$@") > > Recipe duplicated. Would the following work? > > docs/qemu-qmp-ref.7 docs/qemu-ga-ref.7: > $(call quiet-command, \ > perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $< $(@:.7=.pod) && \ > $(POD2MAN) --section=7 --center=" " --release=" " $(@:.7=.pod) > > $@, \ > "GEN","$@") > > Hmm, the recipe is duplicated many times over elsewhere already. > Nevermind, unless you genuinely want to clean that up. > Fixed it in the new series > > > + > > +dvi: qemu-doc.dvi docs/qemu-qmp-ref.dvi docs/qemu-ga-ref.dvi > > +html: qemu-doc.html docs/qemu-qmp-ref.html docs/qemu-ga-ref.html > > +info: qemu-doc.info docs/qemu-qmp-ref.info docs/qemu-ga-ref.info > > +pdf: qemu-doc.pdf docs/qemu-qmp-ref.pdf docs/qemu-ga-ref.pdf > > Would a txt target make sense? > added > > > > > qemu-doc.dvi qemu-doc.html qemu-doc.info qemu-doc.pdf: \ > > qemu-img.texi qemu-nbd.texi qemu-options.texi > qemu-option-trace.texi \ > > qemu-monitor.texi qemu-img-cmds.texi qemu-ga.texi \ > > qemu-monitor-info.texi > > > > +docs/qemu-ga-ref.dvi docs/qemu-ga-ref.html docs/qemu-ga-ref.info > docs/qemu-ga-ref.pdf docs/qemu-ga-ref.txt docs/qemu-ga-ref.7: \ > > +docs/qemu-ga-ref.texi qemu-ga-qapi.texi > > + > > +docs/qemu-qmp-ref.dvi docs/qemu-qmp-ref.html docs/qemu-qmp-ref.info > docs/qemu-qmp-ref.pdf docs/qemu-qmp-ref.txt docs/qemu-qmp-ref.7: \ > > +docs/qemu-qmp-ref.texi qemu-qapi.texi > > + > > + > > ifdef CONFIG_WIN32 > > > > INSTALLER = qemu-setup-$(VERSION)$(EXESUF) > > diff --git a/.gitignore b/.gitignore > > index 3d7848c..d0905c3 100644 > > --- a/.gitignore > > +++ b/.gitignore > > @@ -39,7 +39,7 @@ > > /qmp-introspect.[ch] > > /qmp-marshal.c > > /qemu-doc.html > > -/qemu-doc.info > > +/qemu-doc.info* > > I guess this is to cover the .info-1, .info-2, ... makeinfo produces > when it splits the output. Separate patch, please. > > ok > Perhaps we should consider passing --no-split to makeinfo instead. The > split I get seems rather pointless: .info-2 has a few indexes, all but > one empty, and .info-1 has all the rest, including some indexes. > > done > > /qemu-img > > /qemu-nbd > > /qemu-options.def > > @@ -109,6 +109,15 @@ > > /pc-bios/optionrom/kvmvapic.img > > /pc-bios/s390-ccw/s390-ccw.elf > > /pc-bios/s390-ccw/s390-ccw.img > > +/docs/qemu-ga-ref.html > > +/docs/qemu-ga-ref.txt > > +/docs/qemu-qmp-ref.html > > +/docs/qemu-qmp-ref.txt > > +docs/qemu-ga-ref.info* > > +docs/qemu-qmp-ref.info* > > +/qemu-ga-qapi.texi > > +/qemu-qapi.texi > > +*.tps > > .stgit-* > > cscope.* > > tags > > diff --git a/docs/qmp-intro.txt b/docs/qmp-intro.txt > > index f6a3a03..60deafb 100644 > > --- a/docs/qmp-intro.txt > > +++ b/docs/qmp-intro.txt > > @@ -16,8 +16,7 @@ QMP is JSON[1] based and features the following: > > For detailed information on QMP's usage, please, refer to the following > files: > > > > o qmp-spec.txt QEMU Machine Protocol current specification > > -o qmp-commands.txt QMP supported commands (auto-generated at > build-time) > > -o qmp-events.txt List of available asynchronous events > > +o qemu-qmp-ref.html QEMU QMP commands and events (auto-generated at > build-time) > > > > [1] http://www.json.org > > -- Marc-André Lureau