[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt
From: |
Luiz Capitulino |
Subject: |
Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt |
Date: |
Thu, 26 Jun 2014 08:46:11 -0400 |
On Wed, 25 Jun 2014 14:13:37 -0600
Eric Blake <address@hidden> 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.
- [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt, Michal Privoznik, 2014/06/25
- Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt, Paolo Bonzini, 2014/06/25
- Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt, Eric Blake, 2014/06/25
- Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt, Markus Armbruster, 2014/06/25
- Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt, Luiz Capitulino, 2014/06/25
- Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt, Eric Blake, 2014/06/25
- Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt,
Luiz Capitulino <=
- Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt, Paolo Bonzini, 2014/06/26
- Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt, Eric Blake, 2014/06/26
- Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt, Paolo Bonzini, 2014/06/26
- Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt, Luiz Capitulino, 2014/06/26
- Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt, Paolo Bonzini, 2014/06/26
- [Qemu-devel] [PATCH] qmp: add qmp-events.txt back, Luiz Capitulino, 2014/06/26
- Re: [Qemu-devel] [PATCH] qmp: add qmp-events.txt back, Paolo Bonzini, 2014/06/26
- Re: [Qemu-devel] [PATCH] qmp: add qmp-events.txt back, Eric Blake, 2014/06/26
- Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt, Eric Blake, 2014/06/26
- Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt, Paolo Bonzini, 2014/06/26