U8pdate to FAQ

[Garrett Smith]

Today's FAQ changes include:

1) the entry on formatting date to ISO 8601.
http://jibbering.com/faq/#formatDate

- Thanks to JR Stockton and John G Harris on that.

2) The "books" entry is review-based.
http://jibbering.com/faq/#books
- Thanks to Peter for help with that.

Proposed change to the "meta" section from:

| This document was created for three reasons: to help reduce the high
| levels of noise on c.l.js, to provide a resource for people new to
| javascript, and to point to locations that contain valuable javascript
| resources.

To:
| This FAQ is a reliable javascript that is critically reviewed on
| a daily basis. It also provides resource for learning javascript.


Garrett

 

[Garrett Smith]

Garrett Smith wrote:

[...]

To:
| This FAQ is a reliable javascript that is critically reviewed on
| a daily basis. It also provides resource for learning javascript.

That makes no sense, sorry. Maybe:-

| This FAQ is a reliable resource that is critically reviewed on
| a daily basis.

 

[Osmo Saarikumpu]

1) the entry on formatting date to ISO 8601.
http://jibbering.com/faq/#formatDate

isInRange = year > 0 && year < 9999,

Shouldn't that be:

isInRange = year >= 0 && year <= 9999, //?

Regards, Osmo

 

[Evertjan.]

Garrett Smith wrote on 13 jun 2009 in comp.lang.javascript:

Fixed.

For dates before the year 1, unlike the proleptic Gregorian calendar used
in the international standard ISO 8601, the traditional proleptic Gregorian
calendar (like the Julian calendar) does not have a year 0 and instead uses
the ordinal numbers 1, 2, … both for years AD and BC.

Thus the traditional timeline is 2 BC, 1 BC, AD 1, and AD 2.

ISO 8601 uses astronomical year numbering which includes a year 0 and
negative numbers before it. Thus the ISO 8601 timeline is -0001, 0000,
0001, and 0002.

<http://en.wikipedia.org/wiki/Gregorian_calendar>

 

[Garrett Smith]

Garrett Smith wrote:

Now that I have a little caffeine in me ...

The suggestion of having a short mention of why ISO 8601 was preferred.

The section on Dates has no text in it, directly. It has but one section.

Instead, the section on Dates should have a mention of ISO 8601. The
current one question could be broken into two.

How do I format a date?

How do I parse a common ISO 8601 format?

This change would not significantly alter the material, just break it up
a little.

(fixed typo in Subject).

Garrett -> gym.

 

[Dr J R Stockton]

In comp.lang.javascript message <[email protected]
september.org>, Fri, 12 Jun 2009 19:22:56, Garrett Smith

Today's FAQ changes include:

1) the entry on formatting date to ISO 8601.
http://jibbering.com/faq/#formatDate

- Thanks to JR Stockton and John G Harris on that.

You are premature. Your proposals posted in the group have not been
approved; discussion is continuing. There is at least one change that
has not been presented in the current thread on the topic, and it can be
improved.

Change month to JSmonth, and the code to

JSmonth = parts[2] - 1
date.setFullYear(parts[1], JSmonth, parts[3]);
if ( date.getMonth() != JSmonth ) {

And "with year in" would be better on the next line; your borders mean
that it does not fit on my page. With those borders, 64 characters is
enough.

Also, the routine rejects year 9999.


Code which has not been tested and has not been reviewed here should not
be in the newsgroup FAQ.

To:
| This FAQ is a reliable javascript that is critically reviewed on
| a daily basis. It also provides resource for learning javascript.

After typing that, you should have read it and corrected its "English".
Additionally, "critically" may be taken to imply disapproval.
Also, it's not reviewed on a daily basis. One part is presented daily;
some presentations get responses.

 

[Dr J R Stockton]

In comp.lang.javascript message <[email protected]>

For dates before the year 1, unlike the proleptic Gregorian calendar used
in the international standard ISO 8601, the traditional proleptic Gregorian
calendar (like the Julian calendar) does not have a year 0 and instead uses
the ordinal numbers 1, 2, … both for years AD and BC.

Thus the traditional timeline is 2 BC, 1 BC, AD 1, and AD 2.

A fairly recent tradition.

The years actually ran
... 751 AUC, 752 AUC, 753 AUC, 754 AUC, 755 AUC ... oops no,
... DCCLI, DCCLII, DCCLIII, DCCLIIII, DCCLV ... , all AUC.

 

[Garrett Smith]

In comp.lang.javascript message <[email protected]
september.org>, Fri, 12 Jun 2009 19:22:56, Garrett Smith


You are premature. Your proposals posted in the group have not been
approved; discussion is continuing. There is at least one change that
has not been presented in the current thread on the topic, and it can be
improved.

Change month to JSmonth, and the code to

I understand "month", but what is JSmonth? JavaScript Month?

The convention genereally agreed on is that "upper camel case" is
intended for constructors.

It seems wrong include the letter abbreviation for the common
abbreviation of the language as a variable identifier for that language.

JSmonth = parts[2] - 1
date.setFullYear(parts[1], JSmonth, parts[3]);
if ( date.getMonth() != JSmonth ) {

And "with year in" would be better on the next line; your borders mean
that it does not fit on my page. With those borders, 64 characters is
enough.

Code wrapped at 64 characters? Usually 72 is narrow enough for most
editors (and the newsgroup).

Also, the routine rejects year 9999.

Thanks, fixed.

I had a mistake with manually converting '>' to &amp;gt;=. Well, two,
actually.

Code which has not been tested and has not been reviewed here should not
be in the newsgroup FAQ.

I agree. I did mention that I would be uploading the changed version soon.

After typing that, you should have read it and corrected its "English".

I did. Just not before clicking "send". Posting typos and bungled
grammar to the list is embarrassing. Good think it did not go on the FAQ.

Additionally, "critically" may be taken to imply disapproval.

Possibly. I'm open to suggestions.

The idea is to make the FAQ more reader-friendly, more organized, and
less blah-blah. The tone of the writing is a little condescending in a
few parts.

Telling the reader that they are reading a document that was intended to
reduce noise says that the document they are reading is a preventative
measure that is to benefit the FAQ author/or group regulars. I would
rather have the reader feel that it is worthwhile and personally
beneficial to read the material for the merits of the material.

A reader of the group who gets a "RTFFAQ type of reply" and then
proceeds to duly read the FFaq, and then encounters that would seem a
bit insulted. It seems a little condescending, I think.

I know, typos and broken grammar have the opposite effect of making the
FAQ easy to read. They also diminish the quality. Luckily, I caught
those before they made it in.

The fact that when I post a change to the FAQ generates such a commotion
seems to be evidence that the FAQ is read.

Also, it's not reviewed on a daily basis. One part is presented daily;
some presentations get responses.

By "review" I did not mean that a response-review was posted to the
list, though I can completely see where you are coming from. Moreover,
no response does not imply agreement (as some rude posters might
wishfully think). It would be best to change the wording of that, to
avoid confusion.

| The c.l.js FAQ is a reliable resource that is read and criticized
| by experts. It provides URLs to further information about ECMAScript
| and browser scripting, and some tips to make your stay in
| comp.lang.javascript more enjoyable.

Note: I do not agree with all that you have said. I do appreciate the
technical responses you've provided. You have uncommon knowledge of
Dates and Number. Your knowledge in this area is valuable. Thanks.

Garrett

 

[Dr J R Stockton]

In comp.lang.javascript message <[email protected]
september.org>, Sat, 13 Jun 2009 12:02:45, Garrett Smith

The suggestion of having a short mention of why ISO 8601 was preferred.

Not "was preferred" : "is better".


4 Dates and Times

Unlike others, ISO 8601 formats are language-independent and unambiguous
world-wide; and, for years 0000-9999, are of constant lengths and are
sortable as strings.

* ISO 8601:2004(E)
* http://en.wikipedia.org/wiki/ISO_8601
* Date.prototype, ECMA-262 s.15.9
* http://www.merlyn.demon.co.uk/js-dates.htm // 9 too specific now
// list re-ordered

The section on Dates has no text in it, directly. It has but one section.

Instead, the section on Dates should have a mention of ISO 8601. The
current one question could be broken into two.

How do I format a date?

How do I parse a common ISO 8601 format?

// Format and parse are jargony, and there is no need to use "How do I".
// The true meaning of "parse" is to analyse the structure without
// concern for its meaning; linguistically, "construe" should be used,
// but it's a little esoteric.


4.1 Date Object to ISO Date String

// "Common ISO 8601 Extended formats can be understood internationally,
// without ambiguity."
// The properties are not limited to common ones. Covered above.



// "A local Date object where year >= 0 can be formatted to a common ISO
// 8601 format YYYY-MM-DD with:-"
// For readability, omit spaces around '>=', put one before ':-', and
// maybe use &ge;.


4.2 ISO Date String to Date Object

One must first decide whether it is necessary to check the string for
rigorous compliance with ISO 8601, or whether the input format can be
liberal provided that YYYY-MM-DD is accepted correctly.

// For rigour, use /^(\d{4})-(\d\d)-(\d\d)$/
// Otherwise, use /^\D*([+-]?\d+)\D+(\d\d?)\D+(\d\d?)(\D|$)/


4.3 Time

ISO time formats have corresponding advantages. 12-hour times should be
avoided within processing, and used for input/output only if essential.

// RegExp : /^([01]\d|2[0123])\d\d)\d\d)$/ // untested


4.4 Week Numbering

<weekinfo.htm> <weekcalc.htm> <js-date7.htm>

// Other standards? US official ones?

(fixed typo in Subject).

?? ""

 

[Dr J R Stockton]

In comp.lang.javascript message <[email protected]
september.org>, Sat, 13 Jun 2009 17:41:25, Garrett Smith

I understand "month", but what is JSmonth? JavaScript Month?

Naturally. It cannot refer to me; it has no R.

It seems wrong include the letter abbreviation for the common
abbreviation of the language as a variable identifier for that
language.

It is desirable there, to indicate that the value, while a month and a
number, is not a Gregorian or ISO month number. I personally would
probably use M; in the context one expects that to be related to Month,
but it does not say so strongly that it is a true month.



Comment or text should say that with a two-digit year it is only
necessary to test the month; otherwise, the omission of other tests
might be thought a bludner.

Code wrapped at 64 characters? Usually 72 is narrow enough for most
editors (and the newsgroup).

Then get rid of those pointless borders in the FAQ. I fit 70
characters, boxed, on my Web pages; that just fills the line of a half-
screen default-font window.

Anyway, there's no need for that line to be the longest in the routine.

I rarely read the FAQ off jibbering; I copy it to a local file as HTML
only. Omitting all of the CSS makes it much better; the great gain
outweighs the slight loss.

I had a mistake with manually converting '>' to &amp;gt;=. Well, two,
actually.

I don't have that problem on my site; virtually all code that you see is
your-machine-generated (using code partly guided by LRN) from script on
& tested in that page. You could extract the relevant parts of that
code and make a utility page with two textareas : paste the tested code
in the first, press the intervening button, and copy off the HTML-ised
version.

Possibly. I'm open to suggestions.

The idea is to make the FAQ more reader-friendly, more organized, and
less blah-blah. The tone of the writing is a little condescending in a
few parts.

Too much Cornford.

By "review" I did not mean that a response-review was posted to the
list, though I can completely see where you are coming from.

What you meant is unimportant. What matters is what readers think it
means.

Moreover, no response does not imply agreement (as some rude posters
might wishfully think). It would be best to change the wording of that,
to avoid confusion.

| The c.l.js FAQ is a reliable resource that is read and criticized
| by experts. It provides URLs to further information about ECMAScript
| and browser scripting, and some tips to make your stay in
| comp.lang.javascript more enjoyable.

That sounds both boastful and condescending; typical of US writing, in
fact. Try reading Indian English; they are far more subtle.

Remove it. People come for answers to questions; the FAQ should not
need to explain itself.

 

[Garrett Smith]

In comp.lang.javascript message <[email protected]
september.org>, Sat, 13 Jun 2009 17:41:25, Garrett Smith


Naturally. It cannot refer to me; it has no R.



It is desirable there, to indicate that the value, while a month and a
number, is not a Gregorian or ISO month number. I personally would
probably use M; in the context one expects that to be related to Month,
but it does not say so strongly that it is a true month.



Comment or text should say that with a two-digit year it is only
necessary to test the month; otherwise, the omission of other tests
might be thought a bludner.



Then get rid of those pointless borders in the FAQ. I fit 70
characters, boxed, on my Web pages; that just fills the line of a half-
screen default-font window.

Anyway, there's no need for that line to be the longest in the routine.

I rarely read the FAQ off jibbering; I copy it to a local file as HTML
only. Omitting all of the CSS makes it much better; the great gain
outweighs the slight loss.



I don't have that problem on my site; virtually all code that you see is
your-machine-generated (using code partly guided by LRN) from script on
& tested in that page. You could extract the relevant parts of that
code and make a utility page with two textareas : paste the tested code
in the first, press the intervening button, and copy off the HTML-ised
version.




Too much Cornford.



What you meant is unimportant. What matters is what readers think it
means.




That sounds both boastful and condescending; typical of US writing, in
fact. Try reading Indian English; they are far more subtle.

Remove it. People come for answers to questions; the FAQ should not
need to explain itself.

It seems that had the opposite of intended effect!

I don't see much harm in removing it. WHy not go one more and trim the
following sentence:-

| Each day, one section of the FAQ is posted for review and questions,
| and as a reminder that the FAQ is available.

| Each day, one section of the FAQ is posted for review and questions.


Trimming the "index.html" and "form" from "in HTML form", that brings
the complete entry to:-

| You are reading the comp.lang.javascript meta-FAQ, version 17. It is
| available on the web at http://jibbering.com/faq/ in HTML.
|
| The c.l.js FAQ is a reliable resource that is critically reviewed on a
| daily basis. It provides URLs to further information about ECMAScript
| (loosely called javascript), and some hints and tips to make your stay
| in comp.lang.javascript more enjoyable.
|
| Each day, one section of the FAQ is posted for review and questions,
| and as a reminder that the FAQ is available.
|
| For additional explanation and detail relating to some aspects of the
| FAQ, please see the FAQ Notes. It has been provided separately to
| avoid increasing the size of the FAQ to a point where it would be
| unreasonable to post it to the group.

Garrett

 

[Dr J R Stockton]

In comp.lang.javascript message <[email protected]
september.org>, Mon, 15 Jun 2009 23:51:36, Garrett Smith
<[email protected]> posted:

We only need :-

This is the _FAQ,
_http://jibbering.com/faq/index.html_. Each day, a section of
it is posted to CLJ.

Further material is in the _FAQ Notes_.

It was decided in the past that references to the FAQ should be to the
full URL.

 

[Garrett Smith]

In comp.lang.javascript message <[email protected]
september.org>, Mon, 15 Jun 2009 23:51:36, Garrett Smith
<[email protected]> posted:

We only need :-

This is the _FAQ,
_http://jibbering.com/faq/index.html_. Each day, a section of
it is posted to CLJ.

Further material is in the _FAQ Notes_.

It was decided in the past that references to the FAQ should be to the
full URL.

Telling the reader that:-

| Each day, one section of the FAQ is posted for review and questions,
| and as a reminder that the FAQ is available.

- provides information that is not otherwise apparent. The rest can go.


| Each day, one section of the FAQ is posted to
| _for review and questions.
|
| For additional explanation and detail relating to some aspects of the
| FAQ, please see the FAQ Notes.


Garrett

 

[Dr J R Stockton]

In comp.lang.javascript message <[email protected]
september.org>, Tue, 16 Jun 2009 15:56:47, Garrett Smith

Telling the reader that:-

| Each day, one section of the FAQ is posted for review and questions,
| and as a reminder that the FAQ is available.

- provides information that is not otherwise apparent. The rest can go.

If the reader visits frequently, he'll soon enough realise that.
Otherwise, he does not need to know.