Re: TypeError and use of bold

Cameron McCormack:
>> Do you have a suggestion on how to clarify this?

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

I decided that's too ugly.  Instead, I have linked each instance of
"throw a WhateverError" and each instance of the abstract operations
borrowed from ECMA-262 (ToObject, ToString, etc.) to a paragraph at the
top of the ECMAScript language binding section describing what they
mean.  Check it out.

>>> 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.

I worry about overlinking, here.  Bold upright formatting is used here 
more to offset their use as names from the surrounding text, rather than 
meaning that they are defined terms for which you need to hunt for the 
definition.  I don't think there would be much benefit from linking 
every instance of Number to the ECMAScript spec.  (OTOH, IDL types such 
as "unsigned long" are defined in the spec so I do link those.)

Let me know if the above resolution is satisfactory.

Received on Thursday, 29 December 2011 04:47:41 UTC