Re: Fwd: Deprecating old IDL

On 09/23/2015 10:03 AM, Dominique Hazael-Massieux wrote:
> It looks like the current/old way to encode IDL in ReSpec is on track
> for deprecation; we had discussed previously moving to the new way
> ("contiguous WebIDL"), but we might have to go there sooner than
> previously expected if we want to benefit from the latest changes in
> WebIDL tooling in ReSpec.

Personally, I'd be happy to see us convert to the New Way. The source
looks easier to maintain.

>
> Dom
>
>
>> Begin forwarded message:
>>
>> From: Marcos Caceres <mcaceres@mozilla.com>
>> Subject: Deprecating old IDL
>> Date: September 21, 2015 at 1:27:34 PM CDT
>> To: "spec-prod@w3.org Prod" <spec-prod@w3.org>
>> Resent-To: spec-prod@w3.org
>>
>> Hi All,
>> tl;dr: The ReSpec team (well, mostly just me tbh) 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 Wednesday, 23 September 2015 10:43:01 UTC