Deprecating old IDL

Hi All, 
tl;dr: The ReSpec team would like to start deprecating the use of "old school WebIDL" in ReSpec in favor of "contiguous WebIDL". We will soon begin showing a warning in ReSpec's pill-menu about this. 

For info on contiguous WebIDL: 
http://www.w3.org/respec/guide.html#contiguous-idl
http://www.w3.org/respec/examples/webidl-contiguous.html

===== 

Long version: 
We are deprecating old school WebIDL. What is this "old school WebIDL" you ask? Well, it's IDL you add to a spec by using a <dl>, like:

<dl title="interface FooBar" class="idl">

Other stuff....

</dl>

In its place, we want to encourage you to move to contiguous WebIDL: 

<pre class=idl>
interface FooBar(){
 readonly attribute DOMString baz;
};
</pre>

You can read a little bit about it here:
http://www.w3.org/respec/guide.html#contiguous-idl

And see detailed examples of usage here:
http://www.w3.org/respec/examples/webidl-contiguous.html

## Why?

There are a number of issues with the "old school" approach:

1. Tremendously tedious for authors to maintain. 

2. Tremendous redundancy: the generated tables and other gunk that ReSpec spits out from the IDL is already in the IDL. This leads to needlessly long specs.

3. More seriously, leads to bad specs: specs should be imperative, not declarative. Imperative in that they should define the algorithms/behavior, and not be a collection of statements. Old school IDL lends itself to bad specification practices, by forcing developers to write specs in such a manner. Over the years, we've had to add options to ReSpec like "noLegacyStyle" to avoid such problems, but this has led to other issues with in-document references, etc. Contiguous WebIDL solves this.

We will soon begin showing a warning in ReSpec's pill-menu soon. We will no longer be maintaining the old school code, but documents will continue to work just fine. 

Let me know if you have any questions or comments.

Received on Saturday, 19 September 2015 15:55:51 UTC