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

[Eric Blake]

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.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature