Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Luiz Capitulino <lcapitulino@redhat.com>]

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.