| Message ID | 4b996aea34144d33f2227835dc3d064818ffb7be.1403688576.git.mprivozn@redhat.com |
|---|---|
| State | New |
| Headers | show |
Il 25/06/2014 11:30, Michal Privoznik ha scritto: > Since fe069d9d5946 the qmp-events.txt does not exist anymore. This is > unhappy as users still may want to know what events they can await > from qemu. hxtool however doesn't understand the json format. :( I guess for now we could just revert the deletion, and aim at automatically-generating the documentation in the future. Paolo
On 25.06.2014 11:34, Paolo Bonzini wrote: > Il 25/06/2014 11:30, Michal Privoznik ha scritto: >> Since fe069d9d5946 the qmp-events.txt does not exist anymore. This is >> unhappy as users still may want to know what events they can await >> from qemu. > > hxtool however doesn't understand the json format. :( I guess for now > we could just revert the deletion, and aim at automatically-generating > the documentation in the future. Well, the patch is using 'hxtool -h' which effectively is 'cp'. Yes, it is hackish. Michal
On 06/25/2014 03:30 AM, Michal Privoznik wrote: > Since fe069d9d5946 the qmp-events.txt does not exist anymore. This is > unhappy as users still may want to know what events they can await > from qemu. The .json files are a better contract of what is supported, anyways. > > Signed-off-by: Michal Privoznik <mprivozn@redhat.com> > --- > Makefile | 6 +++++- > 1 file changed, 5 insertions(+), 1 deletion(-) > > diff --git a/Makefile b/Makefile > index 145adb6..b93aa38 100644 > --- a/Makefile > +++ b/Makefile > @@ -77,7 +77,7 @@ LIBS+=-lz $(LIBS_TOOLS) > HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF) > > ifdef BUILD_DOCS > -DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt > +DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt qmp-events.txt Then again, qmp-commands.txt is generated from qmp-commands.hx, which duplicates information already in qapi-schema.json (and friends, now). Would it be better to just install the .json files? Is it time to finally bite the bullet and figure out how to get rid of duplication by dropping qmp-commands.hx, and instead listing example usage directly in the qapi-schema.json file? I'm not sure if we have a good plan in place for user-facing documentation, even if the move to events-as-QAPI was desirable. > ifdef CONFIG_VIRTFS > DOCS+=fsdev/virtfs-proxy-helper.1 > endif > @@ -353,6 +353,7 @@ install-doc: $(DOCS) > $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)" > $(INSTALL_DATA) qemu-doc.html qemu-tech.html "$(DESTDIR)$(qemu_docdir)" > $(INSTALL_DATA) qmp-commands.txt "$(DESTDIR)$(qemu_docdir)" > + $(INSTALL_DATA) qmp-events.txt "$(DESTDIR)$(qemu_docdir)" > ifdef CONFIG_POSIX > $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1" > $(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1" > @@ -455,6 +456,9 @@ qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx > qmp-commands.txt: $(SRC_PATH)/qmp-commands.hx > $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -q < $< > $@," GEN $@") > > +qmp-events.txt: $(SRC_PATH)/qapi-event.json > + $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -h < $< > $@," GEN $@") > + > qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx > $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@," GEN $@") > >
Eric Blake <eblake@redhat.com> writes: > On 06/25/2014 03:30 AM, Michal Privoznik wrote: >> Since fe069d9d5946 the qmp-events.txt does not exist anymore. This is >> unhappy as users still may want to know what events they can await >> from qemu. > > The .json files are a better contract of what is supported, anyways. > >> >> Signed-off-by: Michal Privoznik <mprivozn@redhat.com> >> --- >> Makefile | 6 +++++- >> 1 file changed, 5 insertions(+), 1 deletion(-) >> >> diff --git a/Makefile b/Makefile >> index 145adb6..b93aa38 100644 >> --- a/Makefile >> +++ b/Makefile >> @@ -77,7 +77,7 @@ LIBS+=-lz $(LIBS_TOOLS) >> HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF) >> >> ifdef BUILD_DOCS >> -DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 >> qmp-commands.txt >> +DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 >> qmp-commands.txt qmp-events.txt > > Then again, qmp-commands.txt is generated from qmp-commands.hx, which > duplicates information already in qapi-schema.json (and friends, now). > Would it be better to just install the .json files? Is it time to > finally bite the bullet and figure out how to get rid of duplication by > dropping qmp-commands.hx, and instead listing example usage directly in > the qapi-schema.json file? I'm not sure if we have a good plan in place > for user-facing documentation, even if the move to events-as-QAPI was > desirable. The plan always was to retire qmp-commands.hx once all commands are qapified. Naturally, retiring shouldn't involve loss of useful documentation.
On Wed, 25 Jun 2014 07:56:51 -0600 Eric Blake <eblake@redhat.com> wrote: > On 06/25/2014 03:30 AM, Michal Privoznik wrote: > > Since fe069d9d5946 the qmp-events.txt does not exist anymore. This is > > unhappy as users still may want to know what events they can await > > from qemu. > > The .json files are a better contract of what is supported, anyways. > > > > > Signed-off-by: Michal Privoznik <mprivozn@redhat.com> > > --- > > Makefile | 6 +++++- > > 1 file changed, 5 insertions(+), 1 deletion(-) > > > > diff --git a/Makefile b/Makefile > > index 145adb6..b93aa38 100644 > > --- a/Makefile > > +++ b/Makefile > > @@ -77,7 +77,7 @@ LIBS+=-lz $(LIBS_TOOLS) > > HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF) > > > > ifdef BUILD_DOCS > > -DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt > > +DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt qmp-events.txt > > Then again, qmp-commands.txt is generated from qmp-commands.hx, which > duplicates information already in qapi-schema.json (and friends, now). > Would it be better to just install the .json files? Is it time to > finally bite the bullet and figure out how to get rid of duplication by > dropping qmp-commands.hx, and instead listing example usage directly in > the qapi-schema.json file? I'm not sure if we have a good plan in place > for user-facing documentation, even if the move to events-as-QAPI was > desirable. My original plan was to generate qmp-commands.txt & qmp-evets.txt from the schema file(s). I'm not sure if the .json files are consumable to non-qemu/libvirt developers. If you think they are then I'd be fine with installing them. Wrt the examples, my only concern about having them in the schema is that the examples are in QMP format but in the past we were also planning on having C support via libqmp. If what we have today is what matters, then we can just move the examples to the schema files. > > > ifdef CONFIG_VIRTFS > > DOCS+=fsdev/virtfs-proxy-helper.1 > > endif > > @@ -353,6 +353,7 @@ install-doc: $(DOCS) > > $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)" > > $(INSTALL_DATA) qemu-doc.html qemu-tech.html "$(DESTDIR)$(qemu_docdir)" > > $(INSTALL_DATA) qmp-commands.txt "$(DESTDIR)$(qemu_docdir)" > > + $(INSTALL_DATA) qmp-events.txt "$(DESTDIR)$(qemu_docdir)" > > ifdef CONFIG_POSIX > > $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1" > > $(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1" > > @@ -455,6 +456,9 @@ qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx > > qmp-commands.txt: $(SRC_PATH)/qmp-commands.hx > > $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -q < $< > $@," GEN $@") > > > > +qmp-events.txt: $(SRC_PATH)/qapi-event.json > > + $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -h < $< > $@," GEN $@") > > + > > qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx > > $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@," GEN $@") > > > > >
On 06/25/2014 01:50 PM, Luiz Capitulino wrote: >> Then again, qmp-commands.txt is generated from qmp-commands.hx, which >> duplicates information already in qapi-schema.json (and friends, now). >> Would it be better to just install the .json files? Is it time to >> finally bite the bullet and figure out how to get rid of duplication by >> dropping qmp-commands.hx, and instead listing example usage directly in >> the qapi-schema.json file? I'm not sure if we have a good plan in place >> for user-facing documentation, even if the move to events-as-QAPI was >> desirable. > > My original plan was to generate qmp-commands.txt & qmp-evets.txt from > the schema file(s). I'm not sure if the .json files are consumable to > non-qemu/libvirt developers. If you think they are then I'd be fine with > installing them. The .json files are what _I_ refer to (but I'm probably biased, since I've become a vested partner in the json files in the meantime); for someone encountering the docs with no prior experience, I'm not sure how much value-added the qmp-commands.txt was providing. > > Wrt the examples, my only concern about having them in the schema is > that the examples are in QMP format but in the past we were also planning > on having C support via libqmp. If what we have today is what matters, > then we can just move the examples to the schema files. Putting the examples in the .json files also comes with its own interesting issues - do you prefix every line with # comment markers (so the examples are no longer copy-paste, but now copy-paste-modify)? Or do we do it as top-level JSON elements, perhaps via a new item that the generators ignore but which a doc conversion tool could consume? Maybe: { 'example': { 'client': {"command": {"foo", "arguments": { "hello": "world" } } }, 'server': {"reply": {} } } } Michal's hack at least ensures that we have event documentation, even if the format changed compared to the 2.0 docs, and even if we don't have time to get something better in place before 2.1 goes out. So all of this conversation on ways to do better is nice, but if we don't get there quickly, I could at least live with Michal's patch in the short term.
On Wed, 25 Jun 2014 14:13:37 -0600 Eric Blake <eblake@redhat.com> wrote: > On 06/25/2014 01:50 PM, Luiz Capitulino wrote: > > >> Then again, qmp-commands.txt is generated from qmp-commands.hx, which > >> duplicates information already in qapi-schema.json (and friends, now). > >> Would it be better to just install the .json files? Is it time to > >> finally bite the bullet and figure out how to get rid of duplication by > >> dropping qmp-commands.hx, and instead listing example usage directly in > >> the qapi-schema.json file? I'm not sure if we have a good plan in place > >> for user-facing documentation, even if the move to events-as-QAPI was > >> desirable. > > > > My original plan was to generate qmp-commands.txt & qmp-evets.txt from > > the schema file(s). I'm not sure if the .json files are consumable to > > non-qemu/libvirt developers. If you think they are then I'd be fine with > > installing them. > > The .json files are what _I_ refer to (but I'm probably biased, since > I've become a vested partner in the json files in the meantime); for > someone encountering the docs with no prior experience, I'm not sure how > much value-added the qmp-commands.txt was providing. > > > > > Wrt the examples, my only concern about having them in the schema is > > that the examples are in QMP format but in the past we were also planning > > on having C support via libqmp. If what we have today is what matters, > > then we can just move the examples to the schema files. > > Putting the examples in the .json files also comes with its own > interesting issues - do you prefix every line with # comment markers (so > the examples are no longer copy-paste, but now copy-paste-modify)? Or do > we do it as top-level JSON elements, perhaps via a new item that the > generators ignore but which a doc conversion tool could consume? Maybe: > { 'example': { > 'client': > {"command": {"foo", "arguments": { "hello": "world" } } }, > 'server': > {"reply": {} } > } } > > Michal's hack at least ensures that we have event documentation, even if > the format changed compared to the 2.0 docs, and even if we don't have > time to get something better in place before 2.1 goes out. So all of > this conversation on ways to do better is nice, but if we don't get > there quickly, I could at least live with Michal's patch in the short term. I honestly don't know what's the best thing to do here. I can live with this patch too, although having some introductory comments at the top of the file saying what it is would be nicer.
Il 26/06/2014 14:46, Luiz Capitulino ha scritto: >> > >> > Michal's hack at least ensures that we have event documentation, even if >> > the format changed compared to the 2.0 docs, and even if we don't have >> > time to get something better in place before 2.1 goes out. So all of >> > this conversation on ways to do better is nice, but if we don't get >> > there quickly, I could at least live with Michal's patch in the short term. > I honestly don't know what's the best thing to do here. I can live with > this patch too, although having some introductory comments at the top of > the file saying what it is would be nicer. Can we just revert to the pre-conversion qmp-events.txt file? This is similar to the situation with qmp-commands.hx. Paolo
On 06/26/2014 07:01 AM, Paolo Bonzini wrote: > Il 26/06/2014 14:46, Luiz Capitulino ha scritto: >>> > >>> > Michal's hack at least ensures that we have event documentation, >>> even if >>> > the format changed compared to the 2.0 docs, and even if we don't have >>> > time to get something better in place before 2.1 goes out. So all of >>> > this conversation on ways to do better is nice, but if we don't get >>> > there quickly, I could at least live with Michal's patch in the >>> short term. >> I honestly don't know what's the best thing to do here. I can live with >> this patch too, although having some introductory comments at the top of >> the file saying what it is would be nicer. > > Can we just revert to the pre-conversion qmp-events.txt file? This is > similar to the situation with qmp-commands.hx. As in, carrying redundant information between two files? True that it's no worse than qmp-commands.hx; it would also ensure we aren't regressing on quality of user documentation in relation to prior releases. We could do the restore of that file, but if we do, we should fix the bugs in pre-conversion qmp-events.txt (a couple events were undocumented, there were some grammar errors, all fixed as part of the conversion), as well as document events that have been added post-conversion.
Il 26/06/2014 15:11, Eric Blake ha scritto: >> > >> > Can we just revert to the pre-conversion qmp-events.txt file? This is >> > similar to the situation with qmp-commands.hx. > As in, carrying redundant information between two files? True that it's > no worse than qmp-commands.hx; it would also ensure we aren't regressing > on quality of user documentation in relation to prior releases. We > could do the restore of that file, but if we do, we should fix the bugs > in pre-conversion qmp-events.txt (a couple events were undocumented, > there were some grammar errors, all fixed as part of the conversion), as > well as document events that have been added post-conversion. No events were added post-conversion, since ACPI_DEVICE_OST first went in under the old scheme and Luiz then applied the conversion patch when he did the rebase. We're really close to hard freeze and by extension the release. Do _not_ strive for perfection. Get something that is mostly okay and is an obvious patch. We'll then have 3 weeks to do documentation patches. Paolo
On Thu, 26 Jun 2014 15:14:01 +0200 Paolo Bonzini <pbonzini@redhat.com> wrote: > Il 26/06/2014 15:11, Eric Blake ha scritto: > >> > > >> > Can we just revert to the pre-conversion qmp-events.txt file? This is > >> > similar to the situation with qmp-commands.hx. > > As in, carrying redundant information between two files? True that it's > > no worse than qmp-commands.hx; it would also ensure we aren't regressing > > on quality of user documentation in relation to prior releases. We > > could do the restore of that file, but if we do, we should fix the bugs > > in pre-conversion qmp-events.txt (a couple events were undocumented, > > there were some grammar errors, all fixed as part of the conversion), as > > well as document events that have been added post-conversion. > > No events were added post-conversion, since ACPI_DEVICE_OST first went > in under the old scheme and Luiz then applied the conversion patch when > he did the rebase. > > We're really close to hard freeze and by extension the release. Do > _not_ strive for perfection. Get something that is mostly okay and is > an obvious patch. We'll then have 3 weeks to do documentation patches. The hard freeze argument is a strong one, but my understanding was that we wanted to move away from duplicated information. So reverting is a step back. Any strong objections against this patch?
Il 26/06/2014 15:17, Luiz Capitulino ha scritto: >> > We're really close to hard freeze and by extension the release. Do >> > _not_ strive for perfection. Get something that is mostly okay and is >> > an obvious patch. We'll then have 3 weeks to do documentation patches. > The hard freeze argument is a strong one, but my understanding was that > we wanted to move away from duplicated information. So reverting is a > step back. We sure want to move away from duplicated information. However, at this point we are actively _dropping_ information compared to qmp-events.txt (the examples). Considering that QEMU releases rarely add more than 1 event(*), the amount of duplicated work caused by qmp-events.txt is trivial for the foreseeable future. Of course, the obvious steps to do things "right" are: - automatically generate HTML/DocBook/Texinfo documentation from .json - install the automatically-generated documentation - move examples from qmp-events.txt and qmp-commands.hx to the .json - when qmp-events.txt and qmp-commands.hx are entirely duplicate, kill them But this requires manpower, of course. Paolo (*) Version Events introduced 0.12.0 5 0.13.0 5 0.14.0 3 0.15.0 0 1.0 0 1.1 2 1.2 2 1.3 1 1.4 0 1.5 1 1.6 1 1.7 0 2.0 1 2.1 1
On 06/26/2014 07:25 AM, Paolo Bonzini wrote: > Il 26/06/2014 15:17, Luiz Capitulino ha scritto: >>> > We're really close to hard freeze and by extension the release. Do >>> > _not_ strive for perfection. Get something that is mostly okay and is >>> > an obvious patch. We'll then have 3 weeks to do documentation >>> patches. >> The hard freeze argument is a strong one, but my understanding was that >> we wanted to move away from duplicated information. So reverting is a >> step back. > > We sure want to move away from duplicated information. However, at this > point we are actively _dropping_ information compared to qmp-events.txt > (the examples). > > Considering that QEMU releases rarely add more than 1 event(*), the > amount of duplicated work caused by qmp-events.txt is trivial for the > foreseeable future. Actually, there is a second new event on queue right now: https://lists.gnu.org/archive/html/qemu-devel/2014-06/msg06561.html > > Of course, the obvious steps to do things "right" are: > > - automatically generate HTML/DocBook/Texinfo documentation from .json > > - install the automatically-generated documentation > > - move examples from qmp-events.txt and qmp-commands.hx to the .json > > - when qmp-events.txt and qmp-commands.hx are entirely duplicate, kill them > > But this requires manpower, of course. Sadly, manpower is more frequently devoted to code than to documentation improvements. > > Paolo > > (*) Version Events introduced > 0.12.0 5 > 0.13.0 5 > 0.14.0 3 > 0.15.0 0 > 1.0 0 > 1.1 2 > 1.2 2 > 1.3 1 > 1.4 0 > 1.5 1 > 1.6 1 > 1.7 0 > 2.0 1 > 2.1 1 So depending on Laszlo's series, we may be adding 2 events in 2.1.
Il 26/06/2014 18:25, Eric Blake ha scritto: > Actually, there is a second new event on queue right now: > https://lists.gnu.org/archive/html/qemu-devel/2014-06/msg06561.html Ok. FWIW, I consider that series a bugfix so it can go in after hard freeze. Same for the patch that lets management reconstruct the last RTC_TIME_CHANGE event. Paolo
diff --git a/Makefile b/Makefile index 145adb6..b93aa38 100644 --- a/Makefile +++ b/Makefile @@ -77,7 +77,7 @@ LIBS+=-lz $(LIBS_TOOLS) HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF) ifdef BUILD_DOCS -DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt +DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt qmp-events.txt ifdef CONFIG_VIRTFS DOCS+=fsdev/virtfs-proxy-helper.1 endif @@ -353,6 +353,7 @@ install-doc: $(DOCS) $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) qemu-doc.html qemu-tech.html "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) qmp-commands.txt "$(DESTDIR)$(qemu_docdir)" + $(INSTALL_DATA) qmp-events.txt "$(DESTDIR)$(qemu_docdir)" ifdef CONFIG_POSIX $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1" $(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1" @@ -455,6 +456,9 @@ qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx qmp-commands.txt: $(SRC_PATH)/qmp-commands.hx $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -q < $< > $@," GEN $@") +qmp-events.txt: $(SRC_PATH)/qapi-event.json + $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -h < $< > $@," GEN $@") + qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@," GEN $@")
Since fe069d9d5946 the qmp-events.txt does not exist anymore. This is unhappy as users still may want to know what events they can await from qemu. Signed-off-by: Michal Privoznik <mprivozn@redhat.com> --- Makefile | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-)