Re: Deprecating old IDL

I suggest we wait until *after* we have pushed the latest documents we intend to have for TPAC, but as soon thereafter as possible.  This is to avoid any risk of an incompatible change screwing up our ability to have functional documents available at TPAC.  It's like not installing a new version of your OS just before you go on a trip . . .

-- dan

On Sep 23, 2015, at 6:42 AM, Harald Alvestrand wrote:

> 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 11:51:42 UTC