W3C home > Mailing lists > Public > public-script-coord@w3.org > October to December 2011

Re: TypeError and use of bold

From: Marcos Caceres <marcosscaceres@gmail.com>
Date: Fri, 9 Dec 2011 09:27:17 +0000
Message-Id: <2BB461C6-A525-4BBD-B467-392D3E76807D@gmail.com>
Cc: "public-script-coord@w3.org" <public-script-coord@w3.org>
To: Cameron McCormack <cam@mcc.id.au>


On Dec 9, 2011, at 4:43 AM, Cameron McCormack <cam@mcc.id.au> wrote:

> Hi Marcos,
> 
> Marcos Caceres:
>> TypeError is used throughout the spec, but does not link to its
>> definition (particularly how to throw a TypeError).
> 
> As a slight aside: I have now added predefined exception types corresponding to each of the ECMAScript error types.  Specs can now say "Throw a TypeError" in a non-ECMAScript-specific context and for it to mean something.
> 
> There are two senses of the word "throw" used in the document.
> 
> One is linked to #dfn-throw, which is what other specs should use when they want to throw an IDL exception (or one of the newly predefined ones).  It defines how to create a platform exception object of the right type, set its name property if necessary, and then dispatches it.
> 
> The other is the ECMAScript algorithm sense.
> 
> Do you have a suggestion on how to clarify this?

Maybe include the text above in the spec and define "ECMAScrpt-throw"? It is ugly, but at least it will be clear

> 
>> Also, the use of bold type faces is inconsistent with other specs:
>> bold in other specs is used to denote a formal definition of
>> something. In WebIDL it is used … kinda at random? :(
>> 
>> Please use bold type faces where something is defined, otherwise it's
>> really confusing when searching for definitions.
> 
> It's not random.  There's a guide at the top of the spec on how formatting is used:
> 
>  http://dev.w3.org/2006/webapi/WebIDL/#conventions
> 
> So bold italic is for definitions.  Bold upright is for types.

Ok, sure, but bold upright things should then still be hyperlinked to the right place. Please be mindful that many of us will need to use this spec on a daily basis (I.e., drop in and out looking for defs, but may never read or print the whole document), and little things like this really help make this doc that much more useful. 
Received on Friday, 9 December 2011 09:28:01 UTC

This archive was generated by hypermail 2.3.1 : Wednesday, 8 May 2013 19:30:05 UTC