Re: [PATCH] schemas: Add vim modeline

[Markus Armbruster]

Markus Armbruster <armbru@redhat.com> writes:

> Andrea Bolognani <abologna@redhat.com> writes:
>
>> The various schemas included in QEMU use a JSON-based format which
>> is, however, strictly speaking not valid JSON.
>>
>> As a consequence, when vim tries to apply syntax highlight rules
>> for JSON (as guessed from the file name), the result is an unreadable
>> mess which mostly consist of red markers pointing out supposed errors
>> in, well, pretty much everything.
>>
>> Using Python syntax highlighting produces much better results, and
>> in fact these files already start with specially-formatted comments
>> that instruct Emacs to process them as if they were Python files.
>>
>> This commit adds the equivalent special comments for vim.
>>
>> Signed-off-by: Andrea Bolognani <abologna@redhat.com>
>
> Naming QAPI schema files .json even though their contents isn't was a
> mistake.  Correcting it would be a pain.  If we correct it, then the
> sooner the better.
>
> Renaming them to .py gives decent editor support out of the box.  Their
> contents isn't quite Python, though: true vs. True, false vs. False.  Do
> we care?  Only a few dozen occurences; they could be adjusted.
>
> Renaming them to .qapi would perhaps be less confusing, for the price of
> "out of the box".
>
> Thoughts?

Let me try to summarize the discussion from my point of view.

Basing a DSL on some existing syntax has its advantages: the learning
curve is slightly more gentle, and we get some tooling for free, notably
editor support.

Basing on JSON was a mistake: JSON is designed for data interchange, not
for programming.

To make it fit for programming, we extended it, losing much of what we
gained by basing on existing syntax.

Use of .json file names for the resulting bastard is confusing.

Among the confused are editors.  We unconfuse them one by one by telling
them to treat the files as Python.  Works, because the syntax happens to
be a strict subset of Python's.

We discussed swapping out the base syntax layer for one that is actually
fit for purpose (and doesn't need extending), e.g. YAML.  Radical
change, benefits need to justify the cost.  Possible benefits:

* Better ergonomics for developers

  Depends on what we pick for a base, and how we use it.

  We discussed YAML at some length.  It's complex, and the way it
  assigns types is at odds with the QAPI schema's needs.  I doubt YAML
  could improve ergonomics all that much.

* Not having to maintain our own code for the lower layer

  Replacing the (trivial) JSON parser by glue for an off-the-shelf
  parser is quite unlikely to pay off.

  Replacing the (non-trivial) doc comment parser could be a win, but no
  credible replacements have been suggested so far.

* Make the schema more easily consumable by other programs

  Parsing is the easy part of this problem.  Making the easy part easier
  won't make the total problem appreciably easier.

Right now, I doubt the benefits are worth the cost.  To make me
reconsider, write a concise memo stating the goals, their benefits, the
possible ways to get there, and their cost.

More modest ways to stop our confusing misuse of .json:

* Rename QAPI schema files to .qapi, keep unconfusing tools one by one
  by telling them to treat the files as Python.

* Rename QAPI schema files to .py.  Optionally rename false, true to
  False, True in the schema language, so the schema expressions are
  semantically valid Python.  Humans might still find .py confusing.

* Rename QAPI schema files to .js, change comments from # to //.

* Keep .json, change comments from # to // and strings from ' to ".

  This is still not JSON, but should be close enough to make common
  tooling work.

The last two are too much churn for too little benefit, in my opinion.

I'm willing to do either of the first two.  If you have a preference,
let me know.