comp.lang.javascript Cookbook Proposal

[Peter Michaux]

So for something like an object position-finding function, what kind
of different implementations can you imagine existing? There are so
many factors to consider: doctype, fixed/relative positioning,
borders, scrolling elements, etc. The most efficient solution will
always be one that is written specifically for the exact page it runs
on.

But you can't have a function for "finding the position of a div on a
page that consists of a 3-column layout using floats, a 50px height
header, and a scrolling body with a 10px padding and 2px border." That
would be of no use to anyone. How are you going to decide which
contexts to group together? And is the result actually going to be
useful to anyone? And when you have 5 different solutions hammered out
that handle most common possible contexts, why not group them together
so that a single function can be called to run in any of the contexts?
Why, then you have a general-purpose function!

That is some big piece of bait you're putting out there.

I've read your arguments with Richard about this before. I understand
both sides. They both can be incorporated in my proposal. Each
solution has a stated context. The type of solutions you suggest
Richard would use would have very fine solutions. The type of solution
you seek would have a broader context. In fact there is no real
difference in the type of solutions except breadth of stated context.
In principle I think no one would argue with your type of solution if
they were presented with your context.

Position reporting is one of the more difficult tasks. I think
starting with focused contexts could lead to a broader solution.
However, with many focused solutions it would be easier and then more
likely someone might create other focused solutions when presented
with a new context.

Peter

 

[Matt Kruse]

That is some big piece of bait you're putting out there.

Not intentional. I am obviously biased in my opinions, but I thought
it better to express them and have you weed out what you find
relevant

I've read your arguments with Richard about this before. I understand
both sides. They both can be incorporated in my proposal.

And I think you are one of the most rational and balanced posters in
this group, who understands and sympathizes with different opinions,
priorities, and goals. I trust that if this gets off the ground, that
you will have created something quite useful. I'd recommend that you
solicit suggestions and then drive it how you see fit. Don't cater to
everyone's demands and criticisms (including my own!). I think most
people here would trust your direction.

Matt Kruse

 

[Jeremy]

If you mean http://www.dynamicdrive.com/ then perhaps but definitely
minus the "Cursor Trailer Text" and "Flying Bats Script" ;-) Even with
the existence of that site, I think the group would need to feel
ownership of the content to make it a success. Also I think we would
have no problem focusing on more fundamental and common browser
scripting tasks.



This is why I propose accepting multiple solutions that satisfy
different criteria.



I think that tutorials are great and the faq notes are valuable for
that and don't think they should disappear. However at some point the
English in the tutorials has to be written concretely as JavaScript to
remove all doubt remaining in the English. I've always felt learning
from concrete examples is the best way.

There is no way the repository would ever cover everything and that
probably shouldn't be the goal. After reading and using the repository
a developer would get a feel for the style.

I also don't think we should necessarily try to make a resource that
holds a beginners hand at every step of the way. If we create
something that has value to the regular contributors of the group I
think we have a larger chance at success. I think that perhaps the
lack of value to the regulars themselves is why contributions to the
jibbering site are now more or less extinct.

Peter

Peter, who is the target audience for your idea? If it is a resource
for beginners, do you really think that a beginner is going to be able
to effectively use a subversion repository? If it is not for beginners
- well, do you really think the regulars of the group need such a
resource? Incorporating the conflicting views of group regulars into an
actual library of code won't really work, in my opinion, because it
would be so inconsistent as to be useless to beginners and non-beginners
alike. Furthermore, if you did publish such a library, you would just
get questions on this group asking how to do X with that library. And
this group is not comp.lang.arbitraryjavascriptlibrary.

The idea of a group-maintained documentation source (i.e. a wiki) has
been on the books for over a year. But nobody has done anything! The
purpose of my earlier post was to show that it's a trivial thing to
implement - I did it in under 5 minutes of work. A little less
conversation, a little more action! I personally think an official wiki
is a great idea, because a lot of the questions here are frequently
asked, but there is no logistically sound way to address them all in the
FAQ.

Rather, when a beginner wants to know how to make an asynchronous call,
for example, we could merely point them to the official wiki's entry on
XMLHttpRequest, which would have a well-written explanation of what it
is, a full reference, and some example code - all of which is wiki-fied
so that the user can just click on anything they don't understand and it
will take them to the explanation of *that* object, or function, or
methodology. Any disagreement by you regulars could be handled by
exposing both viewpoints and explaining the merits of each. A wiki is
inherently pretty effective at neutralizing bias, because each side will
edit until both are satisfied with the result.


Jeremy

 

[Dr J R Stockton]

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

I agree whole heartedly and suggest that it is a wikki so that those
who are interested can contribute without needing a single person to
maintain it.

There is, already, the Javascript section of Wikicodia, at <http://www.w
ikicodia.com/wiki/Category:JavaScript>. All that is needed is to
replace most of the articles /in toto/ and most of the content of most
of the rest.

 

[Dr J R Stockton]

In comp.lang.javascript message <[email protected]
glegroups.com>, Thu, 1 Nov 2007 23:53:09, Peter Michaux

<div class="notes">
<p>
In browsers that do not support regular expression literal
syntax,
this code will cause a syntax error. The entire script element
containing this
trim function will not be evaluated and so the trim function
will not
be available. If your set of target browsers is outside the set
of browsers
supported this recipe you should test for the existence of the
trim
function before calling it. For example,
</p>

<code class="use">
if (trim) {
str = trim(str);
}
</code>
</div>

<code>
function trim(str) {
return str.replace(/^\s+|\s+$/g, '');
}
</code>
</div>

Overall, that's a fine example of advising bad scripting.

The code is to be used where there is a need to trim a string. All will
be well with sufficiently recent engines. But if RegExp literals don't
work, the effect of if (trim) is to suppress the warning to the user
that all is not working as intended.

If RegExp literals don't work, then the earlier non-RegExp code must be
used.

If Javascript were fully compiled before distribution, then an
intelligent author/compiler would be able to choose whichever method
seemed best, and incorporate only that one.

But Javascript is not pre-compiled; it is delivered as written. If the
older systems must be supported, the old code must be sent, and there is
no need to send the new code at all, or to do such a test.

Of course, in this case there is the detail that \s and <=32 are not
exact equivalents; so it could be necessary to upgrade the old code to
match \s.

And there's one possible reason for sending both : if the old code is OK
but the new code is better, perhaps by being significantly faster.

 

[Dr J R Stockton]

The Javascript entry in Wikipedia is a joke though. Do I dare point out
the "associative arrays" error or the errors in the sole code block in
the entry? Or, the differences in how Javascript is spelled through out
that page?

Then change it : or, if feeling modest, write what is necessary in the
discussion page. I see Brendan Eich writes there.

 

[RobG]

Peter, who is the target audience for your idea? If it is a resource
for beginners, do you really think that a beginner is going to be able
to effectively use a subversion repository? If it is not for beginners
- well, do you really think the regulars of the group need such a
resource?

Exactly, so it needs to be a resource that is easy to setup and
maintain - i.e. a wikki. It also allows people to contribute
according to their ability - some are more comfortable "gardening" and
maintaining the site, others posting code, and others to review or
editorialise.

It also needs to be written as a learning tool, not as a code library
where people are told "here's some code, just use it". Over time it
should also become a good repository of browser quirks and bugs.

In regard to the wikki you've setup at <URL: http://www.cljwiki.org/

, what are the conditions? How long will it stay up? Who is paying? etc.


[...]
The idea of a group-maintained documentation source (i.e. a wiki) has
been on the books for over a year. But nobody has done anything! The
purpose of my earlier post was to show that it's a trivial thing to
implement - I did it in under 5 minutes of work. A little less
conversation, a little more action! I personally think an official wiki
is a great idea, because a lot of the questions here are frequently
asked, but there is no logistically sound way to address them all in the
FAQ.

The next task should be to post a "why is this resource here" page to
provide a direction for those who visit, then start adding stuff. The
current FAQ and notes provides plenty of content, the archives also
contain a mountain of code that anyone can troll through and use as
the basis of contributions on:

- Libraries vs bespoke code
- How to inject scripts into a page
- XMLHttpRequest and AJAX
- Position (and the zillions of quirks associated with it)
- XML documents
- XPath
- Events
- DOM and various browser quirks

Sites like Quirksmode also offer a great resource, I'm sure people
like PPK or Dean Edwards wouldn't mind being used or linked to.

Rather, when a beginner wants to know how to make an asynchronous call,
for example, we could merely point them to the official wiki's entry on
XMLHttpRequest, which would have a well-written explanation of what it
is, a full reference, and some example code - all of which is wiki-fied
so that the user can just click on anything they don't understand and it
will take them to the explanation of *that* object, or function, or
methodology. Any disagreement by you regulars could be handled by
exposing both viewpoints and explaining the merits of each. A wiki is
inherently pretty effective at neutralizing bias, because each side will
edit until both are satisfied with the result.

Couldn't agree more.

 

[Peter Michaux]

Peter, who is the target audience for your idea?

Anyone who wants to read the captured technical knowledge of the group
and reuse it in their own projects. The higher the probability that
the group contributors can use the resource themselves (eg in their
code or just pointing to it in a post to the group) the more likely
they are to contribute to the resource.

If it is a resource
for beginners, do you really think that a beginner is going to be able
to effectively use a subversion repository?

A complete programming beginner is quite different than an experienced
programmer that is a JavaScript/browser scripting beginner.

A complete programming beginner could read the web site generated by
the build process of the subversion repository.

An experienced programmer would likely know how to use version control
and could pick up subversion quickly if he doesn't know that
particular software.

If it is not for beginners
- well, do you really think the regulars of the group need such a
resource?

I think the regulars could provide a valuable resource to other
JavaScript programmers implementing libraries or building pages "from
scratch".

Incorporating the conflicting views of group regulars into an
actual library of code won't really work, in my opinion, because it
would be so inconsistent as to be useless to beginners and non-beginners
alike.

Hence the need for a small set of editors.

Furthermore, if you did publish such a library, you would just
get questions on this group asking how to do X with that library. And
this group is not comp.lang.arbitraryjavascriptlibrary.

Since the code repository would not be a library but rather a set of
lower level solutions to cross browser problems, these questions would
be appropriate for the group.

One problem of the group is that when questions come it about finding
reusable code or an athoratative browser scripting reference, the
group has little to recommend.

The idea of a group-maintained documentation source (i.e. a wiki) has
been on the books for over a year. But nobody has done anything! The
purpose of my earlier post was to show that it's a trivial thing to
implement - I did it in under 5 minutes of work. A little less
conversation, a little more action! I personally think an official wiki
is a great idea, because a lot of the questions here are frequently
asked, but there is no logistically sound way to address them all in the
FAQ.

An official wiki may be a very good idea. I am only in favor if there
are a few people with access because having good gate keepers is what
can make such a resource useful and reputable. For example, wikipedia
is not a definitive source you should be referencing in a University
thesis.

Rather, when a beginner wants to know how to make an asynchronous call,
for example, we could merely point them to the official wiki's entry on
XMLHttpRequest, which would have a well-written explanation of what it
is, a full reference, and some example code - all of which is wiki-fied
so that the user can just click on anything they don't understand and it
will take them to the explanation of *that* object, or function, or
methodology. Any disagreement by you regulars could be handled by
exposing both viewpoints and explaining the merits of each. A wiki is
inherently pretty effective at neutralizing bias, because each side will
edit until both are satisfied with the result.

It has long been possible to submit new FAQ notes but nobody seems to
do that anymore. Perhaps a wiki format would encourage people or make
faq note maintenance easier but I think a version control system would
be easier anyway if it is a refereed resource. I don't think we need a
wide open access wiki. There are already many places where "anyone"
can write what they like about JavaScript. Wikipedia and other wiki
sites exist and have shown themselves to be as disreputable as
JavaScript books, blogs, code libraries out there. All of these
resources work the same way: lots of content is added with many
mistakes and poor quality JavaScript. The idea is that the quality
improves over time through editing. Since this type of resource style
exists and has shown itself not to produce recommendable JavaScript, I
believe comp.lang.javascript "approved" resources need to work the
opposite way: start with very little JavaScript that is high quality
and grow the resource.

If encouraging more FAQ note style articles is the goal then simply
adding authorship credit might be enough to generate submission. If
having a FAQ note accepted was prestigious accomplishment then
submissions might come out of the woodwork. With the availability of
blogging and personal sites, people are better to build their own
reputation than give away a tutorial to the group with no credit.

I think there is also a market for what I am proposing which is a
concise code library allowing multiple specific solutions to a
particular general problem. These solutions could provide a resource
for writing longer tutorial type articles or code libraries for
specific projects.

Peter

 

[Peter Michaux]

Exactly, so it needs to be a resource that is easy to setup and
maintain - i.e. a wikki. It also allows people to contribute
according to their ability - some are more comfortable "gardening" and
maintaining the site, others posting code, and others to review or
editorialise.

I think if the initial submissions are able to be low quality and
generated at a fast speed, then they will stay low quality as wiki
gardening and editing is a tedious, boring task.

It also needs to be written as a learning tool, not as a code library
where people are told "here's some code, just use it". Over time it
should also become a good repository of browser quirks and bugs.

In regard to the wikki you've setup at <URL:http://www.cljwiki.org/>, what are the conditions? How long will it stay up? Who is paying?

I think group members might feel more comfortable if the groups
resources stay on the jibbering site. Jim has shown he is "sticking
around."

[...]

The idea of a group-maintained documentation source (i.e. a wiki) has
been on the books for over a year. But nobody has done anything! The
purpose of my earlier post was to show that it's a trivial thing to
implement - I did it in under 5 minutes of work. A little less
conversation, a little more action! I personally think an official wiki
is a great idea, because a lot of the questions here are frequently
asked, but there is no logistically sound way to address them all in the
FAQ.

The next task should be to post a "why is this resource here" page to
provide a direction for those who visit, then start adding stuff. The
current FAQ and notes provides plenty of content, the archives also
contain a mountain of code that anyone can troll through and use as
the basis of contributions on:

- Libraries vs bespoke code
- How to inject scripts into a page
- XMLHttpRequest and AJAX
- Position (and the zillions of quirks associated with it)
- XML documents
- XPath
- Events
- DOM and various browser quirks

I'd like to read these articles. If the set of necessary articles is
not to large then just using the current FAQ Notes system is probably
fine. I think new submission would be great. How about submitting some
FAQ Notes articles and see how that goes first?

I'm not opposed to the idea of using wiki software but I am opposed to
the idea that any quality of article can be stamped as
"comp.lang.javascript approved" and the technical experts have to keep
an eye on what is new so that errors can be corrected. The technical
experts may be busy. This process is backwards. Approval needs to come
before something is labeled approved.

Peter

 

[Brian Adkins]

On Nov 2, 11:03 am, Jeremy <[email protected]> wrote:

[ 100+ lines snipped ]

Anyone who wants to read the captured technical knowledge of the group
and reuse it in their own projects. The higher the probability that
the group contributors can use the resource themselves (eg in their
code or just pointing to it in a post to the group) the more likely
they are to contribute to the resource.

Peter, just a minor nitpick, but if you could snip out more lines when
replying (if it doesn't lose important context), it will make for
shorter posts.

 

[beegee]

<div class="problem" id="problem_1">

<p class="statement">
remove whitespace from the beginning and end of a string
</p>

Ok, and regexp is good. I'd like to see more Javascript/DOM related
problems like:

remove and add columns from a table

embed event handlers

highlight rows in a table

how to separate ui from model

etc.

These are things that libraries do but programmers could make a more
informed decision on whether (or not) to use a libary if they knew
how to do them. Also, the implementation of them varies from browser
to browser.

Also, not nearly as informative but real entertaining would be a
collection of flame wars from the archives with chapters such as
"Slamming the Newbie", "You Are Always Wrong", and "The Electrician
and other Narcissists".

So yeah, cookbook is not only a great idea but the hardcopy of it
might be the first worthwhile Javascript book.

Bob

 

[Jeremy]

This site is really just a demo. The point is that I set it up in under
5 minutes of labor, so it would be pretty trivial to do it in a more
"official" context. That being said, the site costs me nothing (beyond
the six and a half dollars I paid for the domain) so I'm just going to
leave it up until aforementioned "official" one is created (at which
point I'll just redirect there). There's no reason people couldn't
start editing if they wish; it's a simple matter to import wiki data
from one source to another.

I think group members might feel more comfortable if the groups
resources stay on the jibbering site.

I agree completely. I would also like to add that permissions
management in the MediaWiki platform is *excellent* and there's no
reason editing couldn't be restricted to a certain set of trusted
maintainers (this can even happen on an entry-by-entry basis).

Jeremy

 

[Dr J R Stockton]

In comp.lang.javascript message <[email protected]
oglegroups.com>, Sat, 3 Nov 2007 07:38:39, Peter Michaux

It has long been possible to submit new FAQ notes but nobody seems to
do that anymore.

The FAQ says nothing about submitting new notes nor of changing existing
ones.

They are just undated, anonymous documents which no-one seems to
maintain.

At least one part is as obviously out-of-date as the corresponding part
of the CLJ FAQ section 1 used to be.

Notes TOC index ends :
The complete FAQ and Notes in ZIP format (174KB)
(1) That should be very useful for anyone who wants to read
comp.lang.javascript FAQ - 8.1 - 2005-11-05
(2) Such links always need a date.

 

[Peter Michaux]

I sent Jim an email and asked about installing Wiki software on the
jibbering server and pointed him to this thread. Hopefully he will
answer me or post here and answer us.

Perhaps we can have our cake and eat it too.

Some people in this thread (eg RobG, Jeremy) are in favor of a wiki
for tutorials.

Other people (eg. Brian, Matt, Me) are more in favor of some sort of
code repository that can be used directly in projects.

I think both are great ideas. "What is a good book on JavaScript?" and
"What library should I use?" are both frequent questions to the group
and with a two pronged approach we can tackle both. Perhaps the
quality of library code out there will eventually improve if some of
our tutorials and code are framed properly.

Trac (http://trac.edgewall.org/) is web-based software management
software. It runs on top of a SVN repository and has a wiki, source
code browser, tickets etc. The Trac wiki could be used for the
tutorials part. The code browser for the repository of code part and
the tickets for both parts. Having it all managed with one piece of
software would give some cohesiveness and would unite it as a single
group project rather than two separate projects.

In my opinion, the FAQ needs to be preserved as a single document and
the daily posts of a single FAQ to the group are useful and should
continue. This is a bit tricky if the whole FAQ is moved into a wiki.
Perhaps the bot that posts daily could screen scrape the FAQ, parse it
and randomly choose a question each day?

The FAQ notes could quite easily be moved into the wiki.

-------

Just to revisit the use of a wiki for the tutorials portion...

Personally I would rather see the tutorials part be text documents in
a SVN repository so non-authorized users can submit patches through
tickets. If a wiki is used and access is limited then I think the wiki
editors will have inefficient workflow. If the wiki access is wide
open then just the spam alone could kill the effort.

Will anyone be able to just arrive to the wiki and have edit
privilages? If not will anyone be able to request a password and be
given edit privilages? If not will there be a set of editors with
discussion of changes on the group? If so who are those editors?

Peter

 

[Jim Ley]

Jeremy said the following on 11/3/2007 5:15 PM:

I sent Jim an email and asked about installing Wiki software on the
jibbering server and pointed him to this thread. Hopefully he will
answer me or post here and answer us.

I'm currently on the road - not that unusual for me, but I'm actually
busy here at the minute and the hotel wifi gives me about 10k
connection - organising a wiki (or svn with auto push out to the site)
is no problem - although I might like to use an alternative server,
but that's already planned, but time is an issue.

either way it's doable, I'm back in the right country with some time
at the end of the week.

Cheers,

Jim.