Updated FAQ (2010-04-01)

[Bwig Zomberi]

On Apr 9, 11:05 am, Bwig Zomberi wrote:

Garrett Smith wrote:
ECMA-262 3rd Edition defines the Global and Math
objects. It also defines these constructors:
Object, Function, Array, String, Boolean, Number,
Date, and RegExp. And it defines these Error
object constructors: Error, EvalError,
RangeError, ReferenceError, SyntaxError,
TypeError and URIError.

[...] The sentence beginning with "And" is
grammatically incorrect.

It isn't.

Use a comma after "and" [...]

That's not necessary, but you may if you wish.

A comma is used to indicate a pause or for the sake of
clarity.

Of course.

[...]

Or use semicolons as Americans would.

Americans use them differently? --Antony

Americans style guides suggest the use of semicolons like
this:

ECMA-262 3rd edition defines the Global and Math objects;
the constructors Object, Function, Array, String,
Boolean, Number, Date, and RegExp; and the Error object
constructors Error, EvalError, RangeError,
ReferenceError, SyntaxError, TypeError and URIError.

Then `no' to answer my own question.

You used a colon, which is like two dots. I suggested the use of a
semicolon, which is like a dot and comma. Colon splits the sentence.
Semicolons keeps it together.

I used the colons for a reason. What you've written is still
hard to parse. It could be read as:

* the constructors Object,
* Function,
* Array,
...
* and the Error object constructors Error,
* EvalError
...

The first one is the worst offender. Obviously -- to our
eyes at least -- that's not the intent, but it's not as easy
to read as it could be either. While there is no need to shy
away from long sentences if they are formulated properly,
there is no need to cram three lists into one sentence
either, and certainly not in a technical document where the
ability to impart understanding trumps writing stylishly
(though I think they often go hand-in-hand). --Antony

Semicolons were not my preference. I suggested a list first. Garett
Smith (quoted below) did not fancy it.

I don't feel so strongly on that.

Usually, semicolons do well to reduce ambiguity. In this case, the
original sentences were Smith's, not mine.

 

[Dr J R Stockton]

In comp.lang.javascript message <[email protected]
september.org>, Fri, 9 Apr 2010 02:19:43, Garrett Smith

Stockton would probably get mad about that. The sentence beginning with
"And" is grammatically incorrect.

A little knowledge is a dangerous thing. And that, in respect of the
English language, is what you have.

Perhaps you are not familiar with the great Blake :
<uggc://ra.jvxvcrqvn.bet/jvxv/Naq_qvq_gubfr_srrg_va_napvrag_gvzr>.

 

[preet]

great faq, i appreciate it

 

[Antony Scriven]

On Apr 10, 7:18 pm, Bwig Zomberi <[email protected]>
wrote:

I suggested:

| ECMA-262 3rd Edition defines the Global and Math objects.
| It also defines these constructors: Object, Function,
| Array, String, Boolean, Number, Date, and RegExp. And it
| defines these Error object constructors: Error,
| EvalError, RangeError, ReferenceError, SyntaxError,
| TypeError and URIError.

You suggested:

| Americans style guides suggest the use of semicolons like
| this:
| ECMA-262 3rd edition defines the Global and Math objects;
| the constructors Object, Function, Array, String,
| Boolean, Number, Date, and RegExp; and the Error object
| constructors Error, EvalError, RangeError,
| ReferenceError, SyntaxError, TypeError and URIError.

[...]

You used a colon, which is like two dots. I suggested the
use of a semicolon, which is like a dot and comma. Colon
splits the sentence. Semicolons keeps it together.

All punctuation splits a sentence in one way or another.
Typically colons are used to introduce a list, though they
have other uses too. And I did not use colons where you used
semicolons: I used full stops. I used the colons to prevent
the ambiguity mentioned below.

It looks awkward but it is functional. If it wasn't
a case of American ingenuity, then a round of
applause for the British.

I used the colons for a reason. What you've written is
still hard to parse. It could be read as:

* the constructors Object,
* Function,
* Array,
...
* and the Error object constructors Error,
* EvalError
...

[...]

Semicolons were not my preference. I suggested a list
first. Garett Smith (quoted below) did not fancy it.

I know. I agreed with you.

Usually, semicolons do well to reduce ambiguity.

In this case they help somewhat, but the main ambiguity
remains.

In this case, the original sentences were Smith's, not
mine.

The original ones were, of course. Nothing you've said
addresses the particular problem of ambiguity that I
explained above. Though since we both agree that a formatted
list would be the most helpful way to present this
information ... --Antony

 

[Garrett Smith]

On Apr 10, 7:18 pm, Bwig Zomberi <[email protected]>
wrote:

I suggested:

| ECMA-262 3rd Edition defines the Global and Math objects.
| It also defines these constructors: Object, Function,
| Array, String, Boolean, Number, Date, and RegExp. And it
| defines these Error object constructors: Error,
| EvalError, RangeError, ReferenceError, SyntaxError,
| TypeError and URIError.

I don't like the way that reads with all the short sentences. The
fullstop is read with a long pause and signifies the end of a thought. I
feel like it is for third graders or something.

You suggested:

| Americans style guides suggest the use of semicolons like
| this:

This reads nicely:

| ECMA-262 3rd edition defines the Global and Math objects;
| the constructors Object, Function, Array, String,
| Boolean, Number, Date, and RegExp; and the Error object
| constructors Error, EvalError, RangeError,
| ReferenceError, SyntaxError, TypeError and URIError.

It can be read aloud and, if read slowly, can be easily understood.

[...]

The original ones were, of course. Nothing you've said
addresses the particular problem of ambiguity that I
explained above. Though since we both agree that a formatted
list would be the most helpful way to present this
information ... --Antony

I can try it with the list and we can see how that looks.

 

[Antony Scriven]

I don't like the way that reads with all the short
sentences. The fullstop is read with a long pause and
signifies the end of a thought. I feel like it is for
third graders or something.

Whereas writing long sentences is a hallmark of clear
writing? And (yes I am beginning of a sentence here) I can
do without the ill-informed argument ad hominem, thank you.

You suggested:

 | Americans style guides suggest the use of semicolons like
 | this:

This reads nicely:

 | ECMA-262 3rd edition defines the Global and Math objects;
 | the constructors Object, Function, Array, String,
 | Boolean, Number, Date, and RegExp; and the Error object
 | constructors Error, EvalError, RangeError,
 | ReferenceError, SyntaxError, TypeError and URIError.

It can be read aloud and, if read slowly, can be easily
understood.

[...]

I think my argument (which you snipped) was quite clear, and
as yet has not been addressed. If it is possible to write
more clearly, then why object? And don't forget that you are
writing from a different standpoint from your target
audience.

I can try it with the list and we can see how that looks.

Thanks, I think it's definitely worth trying. --Antony

 

[Garrett Smith]

Whereas writing long sentences is a hallmark of clear
writing? And (yes I am beginning of a sentence here) I can
do without the ill-informed argument ad hominem, thank you.

I am entitled to my subjective feeling. It is not "ill informed"; it is
how I felt when I read it. It is illogical and unfair to call that "ad
hominem".

I took it that you were trying to help out and I appreciate that fact.

I read them both aloud and found the long sentence separated by
semicolon read much nicer and the one broken into small sentences to be
too clunky or overly simplifistic (See dick drink. See dick drive....)

You suggested:

| Americans style guides suggest the use of semicolons like
| this:

This reads nicely:

| ECMA-262 3rd edition defines the Global and Math objects;
| the constructors Object, Function, Array, String,
| Boolean, Number, Date, and RegExp; and the Error object
| constructors Error, EvalError, RangeError,
| ReferenceError, SyntaxError, TypeError and URIError.

It can be read aloud and, if read slowly, can be easily
understood.

[...]

I think my argument (which you snipped) was quite clear, and
as yet has not been addressed. If it is possible to write
more clearly, then why object? And don't forget that you are
writing from a different standpoint from your target
audience.

I do not see anything unclear about either your wording or Stockton's
but I have the preference for the semicolons and these do avoid ambiguity.

I do not care much for using an unordered list for that but that's just
my opinion.

[...]

 

[Garrett Smith]

[...]

Take a look at this and tell me if it is what you want.

| ECMA-262 3rd edition defines The global object, along with the
| following:
|
| Objects
|
| * Math
| * Object
| * Function
| * Array
| * String
| * Boolean
| * Number
| * Date
|
| Errors
|
| * Error
| * Date
| * EvalError
| * RangeError
| * ReferenceError
| * SyntaxError
| * TypeError
| * URIError

 

[Bwig Zomberi]

I read them both aloud and found the long sentence separated by
semicolon read much nicer and the one broken into small sentences to be
too clunky or overly simplifistic (See dick drink. See dick drive....)

Sentences should be up to the point. To paraphrase Einstein, it should
be simple but not simpler.

On Writing Well, William Zinzer
http://www.cla.wayne.edu/polisci/kdk/general/sources/zinsser.htm

A Plain English Handbook, SEC
http://www.sec.gov/pdf/handbook.pdf

Microsoft Manual Of Style
http://www.google.com/search?hl=en&complete=0&q=mstp.chm&btnG=Search

Developing Quality Technical Information: A Handbook for Writers and
Editors, Gretchen Harris and others, IBM Press
http://www.amazon.co.uk/Developing-Quality-Technical-Information-Information/dp/0131477498

This may not help.
http://www.vsubhash.com/article.asp?id=93&info=Ban_The_British_Language

 

[Garrett Smith]

Sentences should be up to the point. To paraphrase Einstein, it should
be simple but not simpler.

Einstein was not a native speaker of English. The paraphrased advice
seems misapplied and does not seem to serve well to whatever point it is
that you are trying to make.

The point that a sentence should "up to" is a fullstop.

The first linked document does not seem relevant.

The author does provide what I would consider a good example of writing
for the web. The document is long-winded and opinionated.

Ironically, it begins with:
Clutter is the disease of American writing.

 

[Bwig Zomberi]

Einstein was not a native speaker of English. The paraphrased advice
seems misapplied and does not seem to serve well to whatever point it is
that you are trying to make.

The actual quote was "Make everything as simple as possible, but not
simpler." Your "(See dick drink. See dick drive....)" was simpler. What
Antony wanted was probably "simple."

The point that a sentence should "up to" is a fullstop.

Not sure what this means. Full stop is two words.
http://thesaurus.com/browse/pertinent
I meant sentences should pertinent but not convoluted or superfluous.

The first linked document does not seem relevant.

The author does provide what I would consider a good example of writing
for the web. The document is long-winded and opinionated.

It is a classic guide for writing non-fiction. Recommended for writers,
journalists, documenters, etc. It is also a part of academic curriculumn
in the U.S.
http://www.harpercollins.com/books/9780060891541/On_Writing_Well_30th_Anniversary_Edition/index.aspx

 

[Garrett Smith]

[...]

Take a look at this and tell me if it is what you want.

| ECMA-262 3rd edition defines The global object, along with the
| following:
|
| Objects
|
| * Math
| * Object
| * Function
| * Array
| * String
| * Boolean
| * Number
| * Date
|
| Errors
|
| * Error
| * Date
| * EvalError
| * RangeError
| * ReferenceError
| * SyntaxError
| * TypeError
| * URIError

Should the FAQ use that or the paragraph with semicolons?

I'd like to get this one done and keep moving with it.

 

[Dr J R Stockton]

In comp.lang.javascript message <[email protected]
september.org>, Mon, 12 Apr 2010 16:45:33, Garrett Smith

Antony Scriven wrote:
On Apr 11, 12:13 am, Garrett Smith wrote:

Antony Scriven wrote:
On Apr 10, 7:18 pm, Bwig Zomberi <[email protected]>
wrote:

[...]
Take a look at this and tell me if it is what you want.

| ECMA-262 3rd edition defines The global object, along with the
| following:
|
| Objects
|
| * Math
| * Object
| * Function
| * Array
| * String
| * Boolean
| * Number
| * Date
|
| Errors
|
| * Error
| * Date
| * EvalError
| * RangeError
| * ReferenceError
| * SyntaxError
| * TypeError
| * URIError

Should the FAQ use that or the paragraph with semicolons?

I'd like to get this one done and keep moving with it.

It's not clear from that which section of which version of the FAQ you
are proposing to alter; you should be more explicit. It appears to be
the first paragraph of "7 Objects" in FAQ Version 24, Updated
2010-04-10.

The list as above is too sparse. For presentation, I suggest the
*format*

ECMA-262 3rd and 5th editions define
<dl>
<dt>Objects
<dd><i>global</i>, Math
<dt>Constructors
<dd>Object, Function, Array, String, Boolean, Number, Date, RegExp
<dt>Error object constructors
<dd>Error, EvalError, RangeError, ReferenceError, SyntaxError,
TypeError, URIError.
</dl>

All references to the 3rd Edition should be changed to the 3rd and 5th
editions, in all cases where the Editions agree well enough.

 

[Garrett Smith]

In comp.lang.javascript message <[email protected]
september.org>, Mon, 12 Apr 2010 16:45:33, Garrett Smith
[...]


It's not clear from that which section of which version of the FAQ you
are proposing to alter; you should be more explicit. It appears to be
the first paragraph of "7 Objects" in FAQ Version 24, Updated
2010-04-10.

That is correct.

The list as above is too sparse. For presentation, I suggest the
*format*

I thought so, too.

ECMA-262 3rd and 5th editions define
<dl>
<dt>Objects
<dd><i>global</i>, Math
<dt>Constructors
<dd>Object, Function, Array, String, Boolean, Number, Date, RegExp
<dt>Error object constructors
<dd>Error, EvalError, RangeError, ReferenceError, SyntaxError,
TypeError, URIError.
</dl>

That fits a little more compactly. Global is special in this list in
that it does not have an identifier reference. That is why I mentioned
global in the introductory sentence.One might suppose that is what the
<i> is for, as you proposed.

That leaves only one item under "Objects". A DT may have multiple
corresponding DD. Semantically, that could apply here. CSS can be used
to make the list displayed inline.

The text can instead be used as part of the answer to the proposed
question: "What is a built-in object?":

| A built-in object is any object supplied by an ECMAScript
| implementation, independent of the host environment, that is present
| at the start of the execution of an ECMAScript program.
|
| ECMA-262, 3rd Edition defines the following built-in objects:
| <dt>Objects</dt>
| <dd><i>Global</i></dd>
| <dd>Math</dd>
| <dt>Constructors</dt>
| <dd>Object</dd> <dd>Function</dd> <dd>Array</dd>
| <dd>String</dd>
| <dd>Boolean</dd> <dd>Number</dd> <dd>Date</dd> <dd>RegExp</dd>

<dt>Error objects</dt>
<dd>Error</dd> <dd>EvalError</dd> <dd>RangeError</dd>
<dd>ReferenceError</dd> <dd>SyntaxError</dd> <dd>TypeError</dd>
<dd>URIError</dd>

ECMA-262 3rd edition defines the following built-in objects:

| Objects
| global Math
| Constructors
| Object Function Array String Boolean Number Date
| Errors
| Error Date EvalError RangeError ReferenceError
| SyntaxError TypeError URIError

The list for "Errors" displays on one line on the html file.

I have uploaded it so that it can be fully appreciated as HTML.

This is a lot to explain so I uploaded it. It can, of course, be
changed, but I think you'll find it easier to see for yourself than have
me describe it. Here:

All references to the 3rd Edition should be changed to the 3rd and 5th
editions, in all cases where the Editions agree well enough.

Is that to avoid the possible misinterpretation that the 5th Edition has
removed objects?

In addition to those, the 5th Edition defines a built-in JSON object.

 

[Jorge]

I'd like to get this one done and keep moving with it.

7 Objects

7.1 What is a built-in object?
7.2 What is a host object?

There should be an entry about "What is a native object" too.

More so because you use the term "native object" but don't explain its
meaning anywhere in the faq.

And, if "A built-in object is any object supplied by an ECMAScript
implementation, independent of the host environment, that is present
at the start of the execution of an ECMAScript program", then
Object.prototype and Array.prototype and a hundred others are built-in
objects too.

So the phrase "ECMA-262 3rd edition defines the following built-in
objects:" is imprecise as the list does not include all of them, only
some: the global ones.

Either include all of them, or note that the list provided includes
only the global ones.

But I wonder why do you choose to include -arbitrarily- some globals
but not others. IOW, the many other global functions-or-whatever that
aren't constructors (e.g. NaN or decodeURIComponent()).

Maybe it would be better to put a list of each and every global
provided by a conforming implementation. And don't mix them with the
global object, which is their container. The list is ~ :

globalObject= {
Object: ,
Function: ,
Array: ,
String: ,
Boolean: ,
Number: ,
Date: ,
Math: ,
RegExp: ,
JSON: ,
Error: ,
Date: ,
EvalError: ,
RangeError: ,
ReferenceError: ,
SyntaxError: ,
TypeError: ,
URIError: ,
decodeURI: ,
encodeURI: ,
escape: ,
unescape: ,
decodeURIComponent: ,
encodeURIComponent: ,
eval: ,
isFinite: ,
Infinity: ,
NaN: ,
undefined:
};

$ jsc -e 'print(Object.getOwnPropertyNames(this))'
Math,NaN,undefined,Infinity,JSON,Object,Function,Array,Boolean,String,Number,Date,RegExp,Error,EvalError,RangeError,ReferenceError,SyntaxError,TypeError,URIError,eval,parseInt,parseFloat,isNaN,isFinite,escape,unescape,decodeURI,decodeURIComponent,encodeURI,encodeURIComponent,debug,print,quit,gc,version,run,load,checkSyntax,readline,arguments

 

[Jorge]

7 Objects

7.1 What is a built-in object?
7.2 What is a host object?

There should be an entry about "What is a native object" too.

More so because you use the term "native object" but don't explain its
meaning anywhere in the faq.

And, if "A built-in object is any object supplied by an ECMAScript
implementation, independent of the host environment, that is present
at the start of the execution of an ECMAScript program", then
Object.prototype and Array.prototype and a hundred others are built-in
objects too.

So the phrase "ECMA-262 3rd edition defines the following built-in
objects:" is imprecise as the list does not include all of them, only
some: the global ones.

Either include all of them, or note that the list provided includes
only the global ones.

But I wonder why do you choose to include -arbitrarily- some globals
but not others. IOW, the many other global functions-or-whatever that
aren't constructors (e.g. NaN or decodeURIComponent()).

Maybe it would be better to put a list of each and every global
provided by a conforming implementation. And don't mix them with the
global object, which is their container. The list is ~ :

globalObject= {
  Object: ,
  Function: ,
  Array: ,
  String: ,
  Boolean: ,
  Number: ,
  Date: ,
  Math: ,
  RegExp: ,
  JSON: ,
  Error: ,
  Date: ,
  EvalError: ,
  RangeError: ,
  ReferenceError: ,
  SyntaxError: ,
  TypeError: ,
  URIError: ,
  decodeURI: ,
  encodeURI: ,
  escape: ,
  unescape: ,
  decodeURIComponent: ,
  encodeURIComponent: ,
  eval: ,
  isFinite: ,
  Infinity: ,
  NaN: ,
  undefined:

};

$ jsc -e 'print(Object.getOwnPropertyNames(this))'
Math,NaN,undefined,Infinity,JSON,Object,Function,Array,Boolean,String,Numbe r,Date,RegExp,Error,EvalError,RangeError,ReferenceError,SyntaxError,TypeErr or,URIError,eval,parseInt,parseFloat,isNaN,isFinite,escape,unescape,decodeU RI,decodeURIComponent,encodeURI,encodeURIComponent,debug,print,quit,gc,vers ion,run,load,checkSyntax,readline,arguments

"7 Objects" is a good place to introduce the concept of the DOM and
especially the browser's html DOM, and to note that it's a separate
thing that has nothing to do with built-ins.

 

[Dr J R Stockton]

In comp.lang.javascript message <[email protected]
september.org>, Tue, 13 Apr 2010 23:08:59, Garrett Smith

In comp.lang.javascript message <[email protected]
september.org>, Mon, 12 Apr 2010 16:45:33, Garrett Smith

Garrett Smith wrote:
Garrett Smith wrote:
Antony Scriven wrote:
On Apr 11, 12:13 am, Garrett Smith wrote:

Antony Scriven wrote:
On Apr 10, 7:18 pm, Bwig Zomberi <[email protected]>
wrote:

[...]

It's not clear from that which section of which version of the FAQ
you
are proposing to alter; you should be more explicit. It appears to be
the first paragraph of "7 Objects" in FAQ Version 24, Updated
2010-04-10.

That is correct.

The list as above is too sparse. For presentation, I suggest the
*format*

I thought so, too.

ECMA-262 3rd and 5th editions define
<dl>
<dt>Objects
<dd><i>global</i>, Math
<dt>Constructors
<dd>Object, Function, Array, String, Boolean, Number, Date, RegExp
<dt>Error object constructors
<dd>Error, EvalError, RangeError, ReferenceError, SyntaxError,
TypeError, URIError.
</dl>

That fits a little more compactly. Global is special in this list in
that it does not have an identifier reference. That is why I mentioned
global in the introductory sentence.One might suppose that is what the
<i> is for, as you proposed.

That leaves only one item under "Objects". A DT may have multiple
corresponding DD. Semantically, that could apply here. CSS can be used
to make the list displayed inline.

It needs to be inline to avoid sparsity. Would the conversion used for
News sections honour that CSS-inline?

Is that to avoid the possible misinterpretation that the 5th Edition
has removed objects?

No. Changing one reference might do that. It avoids the interpretation
that the 5th has not been considered for that section.

Since that is the only "3rd" after section 3, the "all" may be an "all"
of principle, not of practice. There is an "Ed. 3" and an "Ed 3.0" (why
".0"?); it would be well to use "3rd Edition" throughout, for ease of
search.

 

[Garrett Smith]

In comp.lang.javascript message <[email protected]
september.org>, Tue, 13 Apr 2010 23:08:59, Garrett Smith
[...]

Since that is the only "3rd" after section 3, the "all" may be an "all"
of principle, not of practice. There is an "Ed. 3" and an "Ed 3.0" (why
".0"?); it would be well to use "3rd Edition" throughout, for ease of
search.

Alright then. I'll do that and update the FAQ.

An implementation may supply built-in objects not defined by ECMA-262.
It is worth mentioning that fact.

It is worth considering listing function properties of the built-in object.

Proposed change:
| A built-in object is any object supplied by an ECMAScript
| implementation, independent of the host environment, that is present
| at the start of the execution of an ECMAScript program.
|
| ECMA-262 3rd edition defines the following built-in objects:
|
| Objects
| global, Math
| Constructors
| Object, Function, Array, String, Boolean, Number, Date
| Errors
| Error, Date, EvalError, RangeError, ReferenceError, SyntaxError,
| TypeError, URIError
| Functions
| eval, parseInt, parseFloat, isNaN, isFinite, decodeURI,
| decodeURIComponent, encodeURI, encodeURIComponent
|
| ECMA-262 Ed 5 defines the built-in object JSON.
|
| Nonstandard, built-in objects may include RuntimeObject,
| String.prototype.link, CollectGarbage, and more.

 

[Ry Nohryb]

Proposed change:
| A built-in object is any object supplied by an ECMAScript
| implementation, independent of the host environment, that is present
| at the start of the execution of an ECMAScript program.
|
| ECMA-262 3rd edition defines the following built-in objects:
|
| Objects
|     global, Math
| Constructors
|     Object, Function, Array, String, Boolean, Number, Date
| Errors
|     Error, Date, EvalError, RangeError, ReferenceError, SyntaxError,
| TypeError, URIError
| Functions
|     eval, parseInt, parseFloat, isNaN, isFinite, decodeURI,
| decodeURIComponent, encodeURI, encodeURIComponent
|
| ECMA-262 Ed 5 defines the built-in object JSON.
|
| Nonstandard, built-in objects may include RuntimeObject,
| String.prototype.link, CollectGarbage, and more.

What's up with escape() and unescape() ?

 

[Ry Nohryb]

What's up with escape() and unescape() ?

And with NaN, Infinity and undefined ?