Re: TypeError and use of bold

On Thursday, 29 December 2011 at 04:47, Cameron McCormack wrote:

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

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

Probably not, given that it's a PDF :(  Hopefully they will stop using that nonsense.  
> (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.  
I do wish the conventions did follow HTML5 a bit more... but if no one else thinks it is an issue, I can live with it :)  

Great work on completing this last call phase! spec is really starting to look/work awesomely:)  

Kind regards,
Marcos

Received on Thursday, 29 December 2011 08:45:45 UTC