[ReSpec] release 23.2.0

Discussion:

Marcos Caceres

2018-10-04 10:11:10 UTC

Hi ReSpec users,

Tl;dr:

* citations are now context aware - we call these "smart citations”™️.
* Added support for {{{ IDL.micro[“syntax”] }}}
* TPAC - let’s meet up?

===

We are thrilled to bring you ReSpec 23.2.0, action packed with goodies and fixes.

## Smart citations (Beta!)

“As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.”

We’ve taught ReSpec to understand the difference between normative and informative sections of a specification.

This means that we, Editor’s, don’t need to put “!” In front of citations anymore 🎉 ReSpec intelligently checks if a citation is in a normative or informative section, and automatically does the right thing. Yep, check your References. You are welcome :)

However, if you need to cite something informatively in a normative section, you can use a “?” In front of your reference. Like this:

```
… and fire and event. For example, see how it's done in [[?SOME-SPEC]].
```

Alternatively:

```
… and fire and event. For example, see how it's done in
<a data-cite=“?SOME-SPEC">some spec</a>.
```

We are really proud of this feature and we hope it will make everyone’s lives a bit easier - one less thing to think about!

Note: ReSpec will warn you if you’ve accidentally done the wrong thing (i.e., used a normative reference in an informative section). Check your specs, it might already be yelling at you about this.

Lastly, if your spec is all informative, just do:

```
<body class=“informative">
```

Yep - it’s that easy!

## IDL Micro syntax (BETA)

We’ve implemented a micro-syntax parser for IDL, similar (but different) to the one found in BikeShed. It enforces certain established conventions for writing IDL constructs. For instance:

```

Link to interface’s attribute, {{{ PaymentRequest.id }}}.



Link to interface's method {{{ PaymentRequest.show() }}}.



Link dictionary's member {{{ PayerErrors[“phone"] }}}.


```

We are just getting started on this - and we hope to make it smarter over the coming year.

Any issues, let us know!

## Improvements
We’ve also made countless little bug fixes and improvements behind the scenes over the last few months. See our change log:

https://github.com/w3c/respec/blob/develop/CHANGELOG.md

## TPAC
Looking forward to seeing some of you at TPAC. If you use ReSpec, come say hi, and let me know what you’d like for us to work on next. I can organize a little ReSpec best practices / tips-and-tricks session this year if people are interested.

Thanks!

Tab Atkins Jr.

2018-10-04 18:55:27 UTC

Permalink

Post by Marcos Caceres
* citations are now context aware - we call these "smart citations”™️.

Let me know how this goes - easy to add to Bikeshed too if it ends up
being useful.

Post by Marcos Caceres
* Added support for {{{ IDL.micro[“syntax”] }}}

Hm, any particular reason you diverged from Bikeshed's syntax so
significantly? All of these are the exact same syntax in Bikeshed:

* {{PaymentRequest/id}}
* {{PaymentRequest/show()}}
* {{PayerErrors/"phone"}} (or just {{PayerErrors/phone}}, both work).

(Because all of them, when qualified by the interface/etc they belong
to, occupy shared namespaces, so there's no need to further
distinguish them in syntax.)

It feels like adding more specific syntaxes to these would make it
slightly harder to remember? Are the syntaxes specific to the type
there - could I write {{{ PayerErrors.phone }}}, like JS would allow,
or does that try to indicate an IDL attribute instead?

Post by Marcos Caceres
* TPAC - let’s meet up?

+1

~TJ

Marcos Caceres

2018-10-05 02:07:19 UTC

Permalink

Hi Tab,

Post by Tab Atkins Jr.
Hm, any particular reason you diverged from Bikeshed's syntax so
* {{PaymentRequest/id}}
* {{PaymentRequest/show()}}
* {{PayerErrors/"phone"}} (or just {{PayerErrors/phone}}, both work).

We wanted something that was more “WYSIWYG”. Otherwise, for instance, it’s unclear what {{PayerErrors/phone}} is (an attribute or a member?) without having to open up the whole spec and having a look. Thus, this is helpful (for me) when I’m reviewing PRs, because it’s immediately clear that PayerErrors[“phone”] is talking about a dictionary member.

But I agree that it means that Editors need to know the for Dictionary types, they need to write things `Like[“This”]` (but see below… Foo.bar also works for dictionaries).

Post by Tab Atkins Jr.
(Because all of them, when qualified by the interface/etc they belong
to, occupy shared namespaces, so there's no need to further
distinguish them in syntax.)

I agree - but they way ReSpec works is a little different at the moment: We do inline processing of "{{{ }}}” things before we do IDL parsing (at least, today).

That means we don’t have an IDL AST at that point on which to do the lookups. We will eventually change this, but right now, this works well for most common cases.

Post by Tab Atkins Jr.
It feels like adding more specific syntaxes to these would make it
slightly harder to remember?

I don’t disagree. But it lightens the cognitive load when doing reviews - because “what you see is what you get”: attribute, method(), [“member”], and [[iternal_slot]]. Irrespective {{PayerErrors/phone}} will be converted into markup that renders as `PayerErrors[“phone”]`, so why not just allow it?

Post by Tab Atkins Jr.
Are the syntaxes specific to the type
there - could I write {{{ PayerErrors.phone }}}, like JS would allow,
or does that try to indicate an IDL attribute instead?

Yes, that works too, as it doesn’t yet know how to distinguish IDL container types. If we eventually make this a bit smarter, we will automatically convert {{{ PayerErrors.phone }}} to output `PayerErrors[“phone”]` and link/markup everything correctly.

Tab Atkins Jr.

2018-10-05 18:33:10 UTC

Permalink

Post by Marcos Caceres
Hi Tab,

I mean, that's kinda the point - because of how IDL namespacing works,
specifying the precise type is redundant. All of the top-level types
(interface, dictionary, etc) occupy a shared namespace, so they must
be unique; all of the sub-types, once you specify what top-level type
they're "for", also share a namespace underneath that for-value, so
they must be unique. Knowing the actual type doesn't give you
anything.

If it's important to know that {{PayerErrors/phone}} is an attribute
vs a member, then the reviewer, to be able to review that, must
already know whether PayerErrors is an interface or a dictionary; the
syntax distinction is unimportant. If the reviewer *doesn't care*
whether it's an attribute or member, then the syntax distinction is
unimportant here too.

(It also seems odd to make the distinction here, on the
attribute/member level, rather than at the interface/dictionary level.
{{{PayerErrors}}} doesn't tell you whether it's an interface or a
dictionary - why isn't it helpful for reviewers to provide that
information via syntax here?)

Post by Marcos Caceres
But I agree that it means that Editors need to know the for Dictionary types, they need to write things `Like[“This”]` (but see below… Foo.bar also works for dictionaries).

If, as you say below, `{{{Dict.member}}}` works, then presumably
`{{{Interface["attribute"]}}}` works too? So then the distinction is
purely convention, right, and reviewers can't really depend on it?

Post by Marcos Caceres

Post by Tab Atkins Jr.
(Because all of them, when qualified by the interface/etc they belong
to, occupy shared namespaces, so there's no need to further
distinguish them in syntax.)

I agree - but they way ReSpec works is a little different at the moment: We do inline processing of "{{{ }}}” things before we do IDL parsing (at least, today).
That means we don’t have an IDL AST at that point on which to do the lookups. We will eventually change this, but right now, this works well for most common cases.

Bikeshed works the same way; it processes all `{{foo}}` links into `<a
data-link-type=idl>foo</a>`, which is a link-supertype that covers
*all* of the IDL types, and then only later, when I have parsed the
spec, does it try to actually figure out where it needs to point to.

Post by Marcos Caceres

Post by Tab Atkins Jr.
It feels like adding more specific syntaxes to these would make it
slightly harder to remember?

Ah, in Bikeshed, {{PayerErrors/phone}} does *not* render into that; by
default, the link's text content will just be `phone`. Rendering to
`PayerErrors["phone"]` is odd, because that expression doesn't mean
what it looks like in JS - attributes/methods aren't stored on the
class object, they're on the prototype object. Dictionaries don't even
have corresponding objects. And it's not a meaningful expression in
IDL either. (People do sometimes shorthand `Class.attr` to refer to
the attr for instances of that class, but another common convention is
to use #, like `Class#attr`, to indicate a proto-lookup rather than a
literal object-lookup.)

~TJ

m***@mozilla.com

2018-10-05 21:17:49 UTC

Permalink

Post by Tab Atkins Jr.

Post by Marcos Caceres
Hi Tab,

It does in implementation. The API in c++ is different if it’s a dictionary or an interface. So how one talks about one or the other is different. It does help somewhat to know what type you are dealing with, particularly at a glance.

Post by Tab Atkins Jr.
If it's important to know that {{PayerErrors/phone}} is an attribute
vs a member, then the reviewer, to be able to review that, must
already know whether PayerErrors is an interface or a dictionary; the
syntax distinction is unimportant.

I don’t disagree - but I’ve had requests personally to make the distinction.

Post by Tab Atkins Jr.
If the reviewer *doesn't care*

I’ve had to change enough of these around to know some do.

Post by Tab Atkins Jr.
whether it's an attribute or member, then the syntax distinction is
unimportant here too.

Some do, for better or worse.

Post by Tab Atkins Jr.
(It also seems odd to make the distinction here, on the
attribute/member level, rather than at the interface/dictionary level.
{{{PayerErrors}}} doesn't tell you whether it's an interface or a
dictionary - why isn't it helpful for reviewers to provide that
information via syntax here?)

Mostly just convention in certain specs.

Post by Tab Atkins Jr.

If, as you say below, `{{{Dict.member}}}` works, then presumably
`{{{Interface["attribute"]}}}` works too?

Correct.

Post by Tab Atkins Jr.
So then the distinction is
purely convention, right, and reviewers can't really depend on it?

Yes, it’s for convention in some specs.

Post by Tab Atkins Jr.

Post by Marcos Caceres

Post by Tab Atkins Jr.
(Because all of them, when qualified by the interface/etc they belong
to, occupy shared namespaces, so there's no need to further
distinguish them in syntax.)

I agree - but they way ReSpec works is a little different at the moment: We do inline processing of "{{{ }}}” things before we do IDL parsing (at least, today).
That means we don’t have an IDL AST at that point on which to do the lookups. We will eventually change this, but right now, this works well for most common cases.

Post by Marcos Caceres

Post by Tab Atkins Jr.
It feels like adding more specific syntaxes to these would make it
slightly harder to remember?

Ah, in Bikeshed, {{PayerErrors/phone}} does *not* render into that; by
default, the link's text content will just be `phone`. Rendering to
`PayerErrors["phone"]` is odd,

I agree that it’s odd. It may be something that is currently fashionable with certain folks. If it doesn’t turn out to be something that a lot of editors want to use, we may recommend against using it in the future.

Post by Tab Atkins Jr.
because that expression doesn't mean
what it looks like in JS - attributes/methods aren't stored on the
class object, they're on the prototype object.

I agree and I’m well aware. But not for a dictionary...

Post by Tab Atkins Jr.
Dictionaries don't even
have corresponding objects.

Well, concretely they do - as they are literally js objects.

Post by Tab Atkins Jr.
And it's not a meaningful expression in
IDL either. (People do sometimes shorthand `Class.attr` to refer to
the attr for instances of that class, but another common convention is
to use #, like `Class#attr`, to indicate a proto-lookup rather than a
literal object-lookup.)

Thanks for the additional details.

Post by Tab Atkins Jr.
~TJ

Marcos Caceres

2018-10-08 01:56:39 UTC

Permalink

Post by m***@mozilla.com

Thanks for the additional details.

So, I chewed on what Tab said over the weekend and concluded that Tab is right: the `object[“prop"]` syntax doesn’t significant value.

I’m going to drop support for it, hopefully by the end of the week.

Tab Atkins Jr.

2018-10-08 19:20:56 UTC

Permalink

Post by Marcos Caceres

Post by m***@mozilla.com

Thanks for the additional details.

So, I chewed on what Tab said over the weekend and concluded that Tab is right: the `object[“prop"]` syntax doesn’t significant value.
I’m going to drop support for it, hopefully by the end of the week.

Wait, that's not necessarily what I meant - without it, how do you
refer to an enum value like "foo bar"?

~TJ

Marcos Caceres

2018-10-08 23:49:19 UTC

Permalink

Post by Tab Atkins Jr.
Wait, that's not necessarily what I meant - without it, how do you
refer to an enum value like "foo bar”?
If {{{ window.screen.orientation.type }}} is "landscape-primary", then do Y.

Do you mean for a `maplike` or `setlike`? For those I thought calling `.set\get()` would be appropriate.

Post by Tab Atkins Jr.
{{{ foo.bar.maplikebar.set("enumvalue", otherArg) }}}

Do you have a particular case from a spec in mind?

Tab Atkins Jr.

2018-10-09 15:51:55 UTC

Permalink

Post by Marcos Caceres

I'm confused. The point of {{{foo["bar"]}}} was that "foo" was an
enum, and "bar" was an enum value. Your example here doesn't link up
an enum value at all, so I don't understand the relevance.

Post by Marcos Caceres
Do you mean for a `maplike` or `setlike`? For those I thought calling `.set\get()` would be appropriate.

Post by Tab Atkins Jr.
{{{ foo.bar.maplikebar.set("enumvalue", otherArg) }}}

Do you have a particular case from a spec in mind?

No, I meant an enum. Enum values are strings. While the *convention*
is that the string has no spaces in it (instead using either naked
concatenation, or dash-separation), there's nothing *preventing* us
from having spaces in a multi-word enum value. Such enum values, if
we pretend the enum is a JS object with the enum values as keys, can
*only* be written with [] syntax, not with . syntax.

~TJ

Marcos Caceres

2018-10-09 21:34:32 UTC

Permalink

Post by Tab Atkins Jr.
I'm confused. The point of {{{foo["bar"]}}} was that "foo" was an
enum, and "bar" was an enum value. Your example here doesn't link up
an enum value at all, so I don't understand the relevance.

Sorry, I was still caught up on using `foo["bar"]` to refer to a property of an object, which is why I didn't understand the enum bit.

So, to be clear: I'll remove the ability to do {{{ Dictionary["member"] }}}, but will support {{{ Enum["enum member"] }}}.

For example:

If {{{ window.screen.orientation.type }}} is {{{ OrientationType["landscape-primary"] }}}, then do Y.