Re: cleanups with long-term benefits (was Re: [PATCH] schemas: Add vim modeline)

[Markus Armbruster <armbru@redhat.com>]

Paolo Bonzini <pbonzini@redhat.com> writes:

> On 03/08/20 18:03, Markus Armbruster wrote:
>>> In general it seems like a good idea to use a standard file format and
>>> not "a standard file format except for two characters". :)  We also
>>> wouldn't be having discussions on editors.
>> 
>> No argument.  But towards which standard file format should the schema
>> evolve?
>> 
>> * Standard JSON: no comments, no go
>> 
>> * JSON with # comments: need to change strings from ' to "
>> 
>> * JavaScript: need to change comments from # to //
>> 
>> * Python: may want to switch bool literals from true, false to True,
>>   False
>
> Second or third, I'd say.  I dislike using .py because a stream of
> Python objects doesn't really have a meaning in Python:

It does have a meaning: compute a bunch of dictionaries and throw them
away.  Its useless as a program, but it's not meaningless.

>                                                         that's the
> difference between .js and .json.

True.  RFC 4626: "JSON is a subset of JavaScript, but it is a safe
subset that excludes assignment and invocation."[*]

An analogous subset of Python is possible, but has not been formally
defined as far as I know.

> Third requires someone to do the work in the parser.  Unlikely.

The pain of tweaking the parser is likely dwarved several times over by
the pain of the flag day.

>>> That said, after a bit more research I'm skeptical about the possibility
>>> of using an off-the-shelf parser because most of them either don't
>>> support comments, or are based on YAJL which simply discards comments.
>>>
>>> Since '//' comments are harder to parse than "#" comments, this would
>>> actually _add_ code instead of removing it.  Also since our doc comment
>>> syntax uses "##" as a delimiter, we'd have to bikeshed what the doc
>>> comments would look like ("//!", "///", etc.).
>> 
>> Doc comments don't have to be comments in the schema language.  They
>> could be doc strings.  Requires decent support for long strings, which
>> JSON does not provide.
>
> Exactly.  This was the appeal of YAML (or StrictYAML so that Norwegians
> don't turn into Falsians) as far as I understood.  But if we were to go
> YAML, I'd rather have make doc strings part of the YAML document too.
> That is what Nir suggested, it makes sense but someone has to write the
> conversion code.

To write a converter, you first have to understand the doc comment
language.  It's a bit of a mess, because it was fitted to existing
conventions to reduce churn.

Peter Maydell has patches to generate rST instead of Texinfo.  They
affect the doc comment language.  I expect to merge them for 5.2.

>> If all we want is decent editor support out of the box, then rename to
>> .py, and drop the modelines.  No merge conflicts, no git-blame
>> pollution.
>
> Another possibility is to rename to .qapi and keep Python modelines as a
> hack that does work.

Yes.


[*] Unfortunately, this has become a statement of intent, not a
description of reality, due to JSON design accidents.