Automation of comp.lang.javascript FAQ
Bart Van der Donck
I'm proposing my plan to automate the comp.lang.javascript FAQ
(http://www.jibbering.com/faq/).
-------------------------------------------------
I. Tool for admin
-------------------------------------------------
- Custom interface: [ select chapter ] [ select entry ].
- Textarea to modify the chosen FAQ entry.
- Create new entry in a chapter.
- Edit general settings (headers/footers for output formats and the
like)
I would not advocate the possibility to delete existing entries (or
alter FAQ entry numbers). Perhaps the numbers will going to be referred
to after some time, so I think they should be left intact where
possible.
-------------------------------------------------
II. Crontab manager
-------------------------------------------------
1. Send one FAQ-entry a day to comp.lang.javascript, and keep track of
which one is to send tomorrow. Example of such a post:
http://groups.google.com/group/comp.lang.perl.misc/msg/14ac74ec56339cd9
2. Generate a daily HTML/XML file from MySQL and put it on a fixed
location. Interested websites might fetch this HTML file using their
own preferred tools.
3. Automatically FTP/SFTP it to interested websites. CSS files can be
sent together if necessary.
4. If anyone would prefer this option: auto-email the file to mail
processing scripts.
-------------------------------------------------
III. Technologies
-------------------------------------------------
Database: MySQL.
API: Perl CGI.
DB in text modus: PhpMyAdmin.
Authentication: htaccess.
Custom interface CGI/HTML to FAQ for Admin.
-------------------------------------------------
IV. General goals
-------------------------------------------------
- It should become easier to maintain and adapt the FAQ.
- FAQ can easily be extended with new entries.
- Focus on practical 'quality-proof' code snippets.
- Content could contain much more 'ready-to-go' examples for common
tasks.
- Leave as much room as possible for future extensions.
-------------------------------------------------
V. Data structure
-------------------------------------------------
The current Table of Contents exists of 5 chapters. IMO it would be
better that chapter 4 would be split up in more specific divisions. I
think this would facilitate the navigation, be more logic and is better
towards the future. I do not see any disadvantages to keep chapters
1,2,3,5 as they are now.
--------- Begin proposed TOC ---------
1 meta-FAQ meta-questions
2 comp.lang.javascript tips
2.1 Which newsgroup deals with javascript?
2.2 What questions are off-topic for clj?
2.3 What do I have to do before posting to clj?
2.4 Why was my post not answered?
2.5 How do I direct someone to this FAQ?
2.6 What is ECMAScript?
2.7 What is JScript?
2.8 What are object models?
2.9 What is the document object model?
2.10 Internationalisation in javascript.
2.11 I have a question that is not answered in here
or in any of the resources mentioned here but
I'm sure it has been answered in clj. Where are
the clj archives located?
2.12 What does the future hold for ECMAScript?
3 javascript resources
3.1 What books cover javascript?
3.2 What online resources are available?
4 Data manipulation
4.1. (was: 4.6) How do I convert a Number into a String with
exactly 2 decimal places?
4.2. (was: 4.7) Why does 5 * 1.015 != 5.075 or
0.06+0.01 != 0.07?
4.3. (was: 4.12) Why does parseInt('09') give an error?
4.4. (was: 4.16) How do I trim whitespace - LTRIM/RTRIM/TRIM?
4.5. (was: 4.21) Why does 1+1 equal 11? or How do I convert
a string to a number?
4.6. (was: 4.22) How do I generate a random integer in [1..N]?
4.7. (was: 4.38) How do I download a page to a variable?
4.8. (was: 4.39) How do I access a property of an object using
a string?
4.9. (was: 4.41) Why doesn't the global variable "divId" always
refer to the element with id="divId"?
5 Windows and Frames
5.1. (was: 4.10) How do I check to see if a childwindow is open,
before opening another?
5.2. (was: 4.8) How do I communicate between frames in a web
browser?
5.3. (was: 4.9) How do I find the size of a browser window?
5.4. (was: 4.11) Why does framename.print() not print the correct
frame in IE?
5.5. (was: 4.14) How do I close a window and why does it not work
on the first one?
5.6. (was: 4.15) How do I modify the current page in a browser?
5.7. (was: 4.19) Why do I get permission denied when accessing a
frame/window?
5.8. (was: 4.35) I have window.status="Moomin"; why doesn't the
statusbar change?
6 Forms
6.1. (was: 4.13) How do I get the value of a form control?
6.2. (was: 4.25) My element is named myselect[] , how do I access
it?
6.3. (was: 4.37) How do I POST a form to a new window?
7 Date and time
7.1. (was: 4.30) How do I format Last Modified date with
javascript?
8 Regular Expressions
9 AJAX
10 Browser and system interaction
10.1. (was: 4.2) How can I disable the back button in a
web browser?
10.2. (was: 4.3) How can I access the client-side
filesystem?
10.3. (was: 4.4) How can I see in javascript if a web
browser accepts cookies?
10.4. (was: 4.26) How do I detect Opera/Netscape/IE?
10.5. (was: 4.27) How do I disable the right mouse button?
10.6. (was: 4.32) How do I change the text in the
url/location bar?
10.7. (was: 4.33) How do I prompt a "Save As" dialog for
an accepted mime type?
10.8. (was: 4.36) How do I modify the current browser window?
10.9. (was: 4.42) How do I open a new window with javascript?
10.10. (was: 4.43) How do I get my browser to report
javascript errors?
11 General issues
11.1. (was: 4.1) How do I protect my javascript code?
11.2. (was: 4.5) How can I protect a webpage in javascript?
11.3. (was: 4.17) How do I force a reload from the
server/prevent caching?
11.4. (was: 4.18) How do I get a perl/asp/php variable into
client-side js?
11.5. (was: 4.20) How do I make a 10 second delay?
11.6. (was: 4.23) How do I change print settings with
window.print()?
11.7. (was: 4.24) I have <a href="javascript:somefunction()">
what ... ?
11.8. (was: 4.28) How do I change the confirm box to say
yes/no or default to cancel?
11.9. (was: 4.29) How do I log-out a user when they leave my
site?
11.10. (was: 4.31) Why are my Rollovers so slow?
11.11. (was: 4.34) How do I run a server side script?
11.12. (was: 4.40) When should I use eval?
12 Comments and Suggestions
12.1. (was: 5.1) Why do some posts have <FAQENTRY> in them ?
12.1. (was: 5.2) How do I make a suggestion?
--------- End proposed TOC ---------
Some questions might be shortened to fit into Usenet subject lines.
The major issue here is whether the level-one navigation (chapter 1-12)
is suitable to cover the main pillars of the FAQ entries (also, towards
the future). Of course I'm open for any suggestions here. I think
chapters 6 to 9 are domains where the FAQ is rather silent about,
though I think a lot of javascript programmaers have to deal with these
aspects.
Many regulars have splendid web pages with a lot of good material; I
think this could be an occasion to join the combined expertises. It
might also be a good idea to search the archives for additional common
js problems of the past.
-------------------------------------------------
VI. Project description
-------------------------------------------------
- Programming of CGI, MySQL, Usenet crontab, generate HTML/XML crontab
(FTP/mail scripts are not for first stage).
- Estimated duration: 2 max 4 weeks from the moment I can start the
programming.
- Data of current FAQ is put in database as start position.
- One FAQ-entry a day is automatically posted to comp.lang.javascript.
- I don't have the possibility to invest much time to actually
maintain/extend the FAQ, so I will offer the password to someone in
this group, preferrably a soldier of many wars :-) My private email
address is ba...@yourpantsdotinternet.be (remove yourpants to reply).
I'm also convinced that others have more technical expertise in
javascript than I.
Unless copyright restrictions or objection from CLJ regulars, I think I
could start coding in a week or two.
I'ld be happy to hear any comments or remarks.
--
Bart
Richard Cornford
> I'm proposing my plan to automate the comp.lang.javascript
> FAQ
> (http://www.jibbering.com/faq/).
>
>
> -------------------------------------------------
> I. Tool for admin
> -------------------------------------------------
>
> - Custom interface: [ select chapter ] [ select entry ].
> - Textarea to modify the chosen FAQ entry.
Insufficient: FAQ entries have, and need to have, semantic mark-up (of
some sort) to express the different aspects of their contents. Most
existing entries contain a heading, paragraphs of text that contain
inline code and may contain internal and eternal links, blocks of
example code and blocks of links to external resources.
It is also necessary for blocks of code to be appropriately formatted
for a Usenet post; indented with spaces and laid-out so they will not be
automatically wrapped when viewed (currently a 72 character right
margin).
> - Create new entry in a chapter.
> - Edit general settings (headers/footers for output
> formats and the like)
>
> I would not advocate the possibility to delete existing
> entries (or alter FAQ entry numbers). Perhaps the numbers
> will going to be referred to after some time, so I think
> they should be left intact where possible.
The numbering/ordering are not that important, but it is imperative that
fragment identifiers remain associated with the material that they
currently refer to, else all the references to the FAQ in the achieves
will become broken (seriously hindering people's ability to use archives
for research).
<snip>
> -------------------------------------------------
> IV. General goals
> -------------------------------------------------
>
> - It should become easier to maintain and adapt the FAQ.
> - FAQ can easily be extended with new entries.
> - Focus on practical 'quality-proof' code snippets.
> - Content could contain much more 'ready-to-go' examples
> for common tasks.
> - Leave as much room as possible for future extensions.
Are you sure you are not trying to solve the wrong problem? It has never
been difficult for people to propose/supply content for the FAQ or the
FAQ notes, yet in the last two years the total number of individuals
proposing actual content could be counted on the fingers of one hand.
There are, of course, no shortage of people stating that the FAQ should
contain something on X, Y or Z but who then what to leave it to others
to find the time to do the research, testing, authoring, etc. of that
material.
If people are not capable/willing to find the time to write appropriate
(sufficiently succinct, clear, accurate and useful) FAQ entries it
really doesn't matter how easy it may be to have them included in the
FAQ.
It is unclear from this who it is you are expecting to be
making/creating these FAQ entries. If you make it generally open to
anyone you introduce an administration nightmare for someone. It is a
characteristic of javascript that people become ridiculously
over-confident in their own understanding of the subject following early
superficial 'success' and cannot appreciate how misplaced that early
confidence was until they have gone on to learn a great deal more. This
is the characteristic that results in there being literally hundreds of
thousands of copy-n-past scripts in the Internet that are so bad they
are positively harmful. People who don't know any better don't know any
better, which is a situation that is not altered by their having the
best of intentions.
Consider this fragment of a post to this group in response to a
particular question:-
<quote
cite="news:1139649716.7...@o13g2000cwo.googlegroups.com">
<script type="text/javascript">
void function dummy(args) {
alert('Booh!');
}
window.onload = dummy;
...
Function dummy is being parsed and allocated on script load,
but void operator prevents the script context to get a reference
on the allocated memory heap. So it becomes garbage collector
ready right away.
</quote>
- it is a fantasy; and expression of misconceptions couched in half
understood jargon and having no relationship with the reality of
javascript at all. Yet its author was absolute convinced that this
nonsense was an answer to a question posted here. The problem being that
if you give anyone the opportunity to add material to the FAQ you will
be getting a great number of people adding entries that are false,
ill-considered, harmful, bad and ranging right up to the full-on fantasy
expressed above, and probably doing this with the best intentions in the
world.
Somebody is going to have to be responsible for weeding this stuff back
out again, and if the number of people adding worthwhile entries is as
low as the number contributing such over the last two years it might end
up being the case that the net effect of weeding out what should not be
in the FAQ is no actual change over time, but no changed achieved at
considerably greater effort on the part of however is doing the weeding
out.
Richard.
Bart Van der Donck
> Bart Van der Donck wrote:
> > I'm proposing my plan to automate the comp.lang.javascript
> > FAQ
> > (http://www.jibbering.com/faq/).
> >
> > -------------------------------------------------
> > I. Tool for admin
> > -------------------------------------------------
> >
> > - Custom interface: [ select chapter ] [ select entry ].
> > - Textarea to modify the chosen FAQ entry.
>
> Insufficient: FAQ entries have, and need to have, semantic mark-up (of
> some sort) to express the different aspects of their contents.
Yes. Those could be marked by the author within the <textarea> of the
FAQ-entry, either fully typed (like <important>special
thing</important>) or handled by some client script code. As long as
the end result to the processing server script is identical.
> Most existing entries contain a heading, paragraphs of text that
> contain inline code and may contain internal and eternal links,
> blocks of example code and blocks of links to external resources.
I think it's a question of agreements; there are a number of technical
possibilities. For example, the items that you mention:
Heading (=title of FAQ-entry?): I would think of this as a separate
table column in MySQL. The output format towards HTML could be "<h3>
<a name='FAQ_$nr'>$title</a></h3>"; towards XML
"<heading>title</heading>"; towards Usenet "-----------\nFAQ $nr:
$title\n-----------\n\n".
Paragraph: in HTML/XML "<p>$content</p>"; for Usenet "$content\n\n".
Inline code: in HTML/XML "<code>$code</code>", in Usenet add 2 spaces
for and after the code (like: if you want to say hello, then
alert("hi"); will help you.)
Alternatively there is, as far as I know, a notation like ``
alert("hi!"); '', but I think this is easier to confuse.
Internal links: not possible in Usenet, I'ld propose common anchors for
HTML, not sure for XML.
External links: HTML/XML "<a href='$link' target='_blank'>$link</a>",
Usenet just the URL.
Blocks of links: HTML/XML: "<linkblock>$links</linkblock>" or the
<div>'s as they are right now. Usenet: I think just 2 \n before and
after the block should be the most logical display method.
Blokcs of code: in HTML/XML "<codeblock>$code</codeblock>", for Usenet
start each line with 3 spaces.
These are just examples; these formats should just be agreed.
> It is also necessary for blocks of code to be appropriately formatted
> for a Usenet post; indented with spaces and laid-out so they will not be
> automatically wrapped when viewed (currently a 72 character right
> margin).
This is a good remark indeed. Each code line should then exist of no
more than 68 characters (say +3 initial blanks, plus one safe char).
The programming code should be entered into the database like that; I
don't see any other way.
> > [...]
> > I would not advocate the possibility to delete existing
> > entries (or alter FAQ entry numbers). Perhaps the numbers
> > will going to be referred to after some time, so I think
> > they should be left intact where possible.
>
> The numbering/ordering are not that important, but it is imperative that
> fragment identifiers remain associated with the material that they
> currently refer to, else all the references to the FAQ in the achieves
> will become broken (seriously hindering people's ability to use archives
> for research).
Perhaps it's a good idea to abandon my proposed TOC and just keep the
current divisions as they are now.
> [...]
> Are you sure you are not trying to solve the wrong problem? It has never
> been difficult for people to propose/supply content for the FAQ or the
> FAQ notes, yet in the last two years the total number of individuals
> proposing actual content could be counted on the fingers of one hand.
> There are, of course, no shortage of people stating that the FAQ should
> contain something on X, Y or Z but who then what to leave it to others
> to find the time to do the research, testing, authoring, etc. of that
> material.
>
> If people are not capable/willing to find the time to write appropriate
> (sufficiently succinct, clear, accurate and useful) FAQ entries it
> really doesn't matter how easy it may be to have them included in the
> FAQ.
>
> It is unclear from this who it is you are expecting to be
> making/creating these FAQ entries. If you make it generally open to
> anyone you introduce an administration nightmare for someone. It is a
> characteristic of javascript that people become ridiculously
> over-confident in their own understanding of the subject following early
> superficial 'success' and cannot appreciate how misplaced that early
> confidence was until they have gone on to learn a great deal more. This
> is the characteristic that results in there being literally hundreds of
> thousands of copy-n-past scripts in the Internet that are so bad they
> are positively harmful. People who don't know any better don't know any
> better, which is a situation that is not altered by their having the
> best of intentions.
As I mentionned in another thread "CLJ newsgroup FAQ", I think it's
best to just have one password indeed. Let's say I would give it to Jim
Ley, who is, AFAIK, the best placed person to further decide to whom he
wants to pass it. I give FTP access, a webbased tool for easy/quick FAQ
admin, PhpMyAdmin and full access to the Perl source files.
It's not my intention to actually maintain the content of the FAQ. I
have some ideas about how the content could be improved though, but
those are perhaps of minor importance here; it's just what I think of
it. I should perhaps limit myself here to make the technical
background.
I do not comment on your further paragraphs, as I think these are all
content-related.
I'm posting a proposal for the table design here. Fields with identical
names are linked as follows:
[chapters.chaptersID] to [entries.chaptersID]: 1 on N
[contributors_entries.entriesID] to [entries.entriesID]: N on 1
[contributors.contributorsID] to [contributors_entries.contributorsID]:
1 on N
Table [outputsettings] could then hold the actual output parameters
(e.g. sender name, sender email address, Usenet header text, etc.). The
"lastupdate_by" fields are thought to hold IP-addresses. FAQ 4.11.
would have chapterNR 4 and entriesNR 11.
CREATE TABLE `chapters` (
`chaptersID` smallint(6) NOT NULL auto_increment,
`chapterNR` smallint(6) NOT NULL default '0',
`title` varchar(255) NOT NULL default '',
`remarks_internal` text NOT NULL,
`lastupdate` timestamp(14) NOT NULL,
`created` datetime NOT NULL default '0000-00-00 00:00:00',
`lastupdate_by` varchar(30) NOT NULL default '',
`tmp1` char(1) NOT NULL default '',
`tmp2` char(1) NOT NULL default '',
`tmp3` char(1) NOT NULL default '',
PRIMARY KEY (`chaptersID`),
KEY `chapterNR` (`chapterNR`)
);
CREATE TABLE `contributors` (
`contributorsID` int(11) NOT NULL auto_increment,
`name` varchar(255) NOT NULL default '',
`email` varchar(255) NOT NULL default '',
`remarks_internal` text NOT NULL,
`lastupdate` timestamp(14) NOT NULL,
`created` datetime NOT NULL default '0000-00-00 00:00:00',
`lastupdate_by` varchar(30) NOT NULL default '',
`tmp1` char(1) NOT NULL default '',
`tmp2` char(1) NOT NULL default '',
`tmp3` char(1) NOT NULL default '',
`tmp4` char(1) NOT NULL default '',
PRIMARY KEY (`contributorsID`)
)
CREATE TABLE `contributors_entries` (
`contributors_entriesID` int(11) NOT NULL auto_increment,
`entriesID` int(11) NOT NULL default '0',
`contributorsID` int(11) NOT NULL default '0',
PRIMARY KEY (`contributors_entriesID`),
KEY `entriesID` (`entriesID`,`contributorsID`)
);
CREATE TABLE `entries` (
`entriesID` int(11) NOT NULL auto_increment,
`chaptersID` smallint(6) NOT NULL default '0',
`entriesNR` smallint(6) NOT NULL default '0',
`entry_question` varchar(255) NOT NULL default '',
`entry_answer` text NOT NULL,
`remarks_internal` text NOT NULL,
`lastupdated` timestamp(14) NOT NULL,
`created` datetime NOT NULL default '0000-00-00 00:00:00',
`lastupdate_by` varchar(30) NOT NULL default '',
`tmp1` char(1) NOT NULL default '',
`tmp2` char(1) NOT NULL default '',
`tmp3` char(1) NOT NULL default '',
`tmp4` char(1) NOT NULL default '',
`tmp5` char(1) NOT NULL default '',
`tmp6` char(1) NOT NULL default '',
PRIMARY KEY (`entriesID`),
KEY `chaptersID` (`chaptersID`,`entriesNR`)
);
CREATE TABLE `outputsettings` (
`outputsettingsID` smallint(6) NOT NULL auto_increment,
`definition` varchar(255) NOT NULL default '',
`content` text NOT NULL,
`explanation` text NOT NULL,
`remarks_internal` text NOT NULL,
`lastupdate` timestamp(14) NOT NULL,
`created` datetime NOT NULL default '0000-00-00 00:00:00',
`lastupdate_by` varchar(30) NOT NULL default '',
`tmp1` char(1) NOT NULL default '',
`tmp2` char(1) NOT NULL default '',
`tmp3` char(1) NOT NULL default '',
PRIMARY KEY (`outputsettingsID`)
);
--
Bart
Dr John Stockton
Jul 2006 19:48:00 remote, seen in news:comp.lang.javascript, Richard
Cornford <Ric...@litotes.demon.co.uk> posted :
>Bart Van der Donck wrote:
>The numbering/ordering are not that important, but it is imperative that
>fragment identifiers remain associated with the material that they
>currently refer to, else all the references to the FAQ in the achieves
>will become broken (seriously hindering people's ability to use archives
>for research).
The past must not be allowed to constrain the future detrimentally,
except if inevitable. We managed to update the Calendar in 1752, and
the Netherlanders did it on several occasions (Groningen: 1583, -1594,
1701); we should be able to update a FAQ.
There is advantage in having a fixed number of digits in a numbering
system. So keep the Old Style FAQ, as is; and begin a New Style FAQ
with the major and minor sections numbered each numbered from 10 to 99,
or 100 to 999.
>Are you sure you are not trying to solve the wrong problem? It has never
>been difficult for people to propose/supply content for the FAQ or the
>FAQ notes, yet in the last two years the total number of individuals
>proposing actual content could be counted on the fingers of one hand.
>There are, of course, no shortage of people stating that the FAQ should
>contain something on X, Y or Z but who then what to leave it to others
>to find the time to do the research, testing, authoring, etc. of that
>material.
The lack of proposals is probably strongly affected by the rareness of
actual FAQ updates.
At least some suggestions would have taken negligible research and
testing, given the general level of knowledge here, and would have been
easy to author.
The FAQ maintainer, who writes at great frequency and length in the
group, could easily have replied to such suggestions with something in
News like "Seems worthwhile, please suggest wording in News"; the
suggested wording should be OK once the resulting debate dies down.
I've suggested before that, rather than being a repeat of Monday's, the
Friday post could be different - for example a plain-text record of
{FaqEntry}-type sections of posts.
E.G. Jeremy asks about RegExp \b ; I {FaqEntry} about the FAQ needing
more on RegExps ; someone writes a {FaqEntry} that FAQ 4.16 Link 2 is in
fact to MAN-page-type RegExp documentation, but typographically
horrible; someone else points to a nicer presentation of that material
(I know there has been one, but I don't know where) ; someone provides a
final {FaqEntry} version in plain-text ; the maintainer notes "Seems OK
to me", and will later move it into Monday or Wednesday. Superseded
bits of discussion get chopped.
Granted, there are many moves for the maintainer to do; but they largely
consist just of copying anything plausible from News and pasting it into
the Friday text.
<FAQENTRY> DRAFT
4.nn How is String Manipulation best done?
The String Object has simple methods such as indexOf; but, especially
for complex string manipulation tasks, methods using RegExps can be much
more useful. RegExps allow sought-for structures to be expressed
compactly.
BOX -----------
http://docs.sun.com/source/816-6408-10/regexp.htm - RegExp Object
http://msdn.microsoft.com/library/en-us/script56/html/js56reconIntroduct
ionToRegularExpressions.asp - ???
...?
---------------
The first box in *4.16* shows simple usage of String.replace with a
RegExp literal argument.
BOX -----------
Example using String.match() - maybe
function Part(YMD) { // Date components to Array
return YMD.value.match(/^([+-]?\d+)\D+(\d+)\D+(\d+)$/) }
Example using /RegExp/.test() - maybe
if (!/(.*)\s+([a-z]+)/i.test(DTstr.replace(/-/g, "/")))
return NaN // cannot be Date + Abbr
Example of var RE = /RegExp/ // and/or new RegExp()
---------------
DRAFT </FAQENTRY>
Now we need a small-country person to rewrite that in simpler English!
--
© John Stockton, Surrey, UK. ?@merlyn.demon.co.uk Turnpike v4.00 IE 4 ©
<URL:http://www.jibbering.com/faq/>? JL/RC: FAQ of news:comp.lang.javascript
<URL:http://www.merlyn.demon.co.uk/js-index.htm> jscr maths, dates, sources.
<URL:http://www.merlyn.demon.co.uk/> TP/BP/Delphi/jscr/&c, FAQ items, links.
Richard Cornford
> Richard Cornford wrote:
>> Bart Van der Donck wrote:
>>> I'm proposing my plan to automate the comp.lang.javascript
>>> FAQ
>> The numbering/ordering are not that important, but it is
>> imperative that fragment identifiers remain associated with
>> the material that they currently refer to, else all the references
>> to the FAQ in the achieves will become broken (seriously hindering
>> people's ability to use archives for research).
>
> Perhaps it's a good idea to abandon my proposed TOC and just
> keep the current divisions as they are now.
While I would disagree with your specific categories, splitting section
4 up into sub categories probably is a good aim, and doing so does not
necessitate breaking the existing fragment identifiers. They may
currently be a coincidental by-product of the way the FAQ is generated
but if the arrangement was switched to using arbitrary named fragment
identifiers (preferably meaningful names for future entries) then the
existing numeric fragment identifiers can be retained as identifiers for
the existing entries. I just don't think it would be a good idea to
throw them out.
>> [...]
>> Are you sure you are not trying to solve the wrong problem? ...
<snip>
Richard.
Richard Cornford
> Richard Cornford wrote:
<snip>
>>Are you sure you are not trying to solve the wrong problem?
>>It has never been difficult for people to propose/supply
>>content for the FAQ or the FAQ notes, yet in the last two
>>years the total number of individuals proposing actual content
<snip>
>
> The lack of proposals is probably strongly affected by the
> rareness of actual FAQ updates.
As the rate of not receiving proposals for actual content has not
altered with time that relationship is questionable.
> At least some suggestions would have taken negligible
> research and testing, given the general level of knowledge
> here, and would have been easy to author.
>
> The FAQ maintainer, who writes at great frequency and length
> in the group, could easily have replied to such suggestions
> with something in News like "Seems worthwhile, please suggest
> wording in News"; the suggested wording should be OK once the
> resulting debate dies down.
Are you suggesting that I have not asked people to propose wording for
their suggestions? If an action is reliably fruitless shouldn't it be
expected to be recognised as fruitless and abandoned?
> I've suggested before that, rather than being a repeat of
> Monday's, the Friday post could be different - for example
> a plain-text record of {FaqEntry}-type sections of posts.
Jim's automated posting script did what Jim's automated posting script
did. It was written in a language that I don not know and so I was not
in a position to change what it did. A replacement posting script may do
something differently but the underwhelming rush of competent
Perl/python programmers responding to Jim's request for a replacement
that would satisfy the changed authentication requirement doesn't
suggest much hope change, let alone enhancements.
> E.G. Jeremy asks about RegExp \b ; I {FaqEntry} about the
> FAQ needing more on RegExps ; someone writes a {FaqEntry}
> that FAQ 4.16 Link 2 is in fact to MAN-page-type RegExp
> documentation, but typographically horrible; someone else
> points to a nicer presentation of that material (I know
> there has been one, but I don't know where) ; someone
> provides a final {FaqEntry} version in plain-text ; the
> maintainer notes "Seems OK to me", and will later move it
> into Monday or Wednesday. Superseded bits of discussion get
> chopped.
"someone writes ... "
"someone else points to ... "
"someone provides ... "
It is a nice idea, but there is no point trying to convince me, you need
to talk that "someone" into playing their part.
I would remind you of what happened last time I proposed new content for
the FAQ. A vague and broad request for additions was made, I spent some
time considering how the request could best be addressed and posted some
actual proposals, you quibbled about the wording and everyone else
remained completely silent. Leaving me to invent some alternative
wording, which if it had been apparent to me I would have used in the
first place.
<snip>
> <FAQ**TRY> DRAFT
> 4.nn How is String Manipulation best done?
I cannot see a blanket statement about how string manipulation is "best
done" as something that could be addressed in a "quick answer". "Best"
is far too context related when it comes to working with strings.
> The String Object has simple methods such as indexOf;
Without mentioning the relationship between string primitives and String
objects? An area that is frequently confused in the minds of novices.
> but, especially for complex string manipulation tasks, methods
> using RegExps can be much more useful.
You cannot say "RegExps" in place of regular expressions. Certainly not
here, if at all.
> RegExps allow sought-for structures to be expressed
> compactly.
Is that sentence going to convey meaning?
<snip>
> DRAFT </FAQ**TRY>
You may not appreciate it but I have put a great deal of thought into
how regular expressions should be covered by the FAQ (as " the FAQ
should say something about regular expressions is a recurring request).
Baring in mind that regular expressions alone represent no less than 10%
of the language specification they certainly should have more and better
coverage, but I think that any 'quick answer' could, at best, be an
entry point, and that entry point would be best pitched as an answer to
a form validation question if it is going to avoid having to expand
itself into something too larger to be a quick answer.
> Now we need a small-country person to rewrite that in
> simpler English!
<snip>
Attempting to further restrict possibilities is unlikely to increase the
chances that "someone" will actually do it.
Richard.
Bart Van der Donck
> Are you sure you are not trying to solve the wrong problem? ...
As I understand, the main problem is rather content-related and not
technical. Yes, I'm ready to do some proposals now and then in this
newsgroup:
- concise and preferably common problems
- quality response
- easy to copy/paste for FAQ maintainer
- what's already in the archive
--
Bart
Bart Van der Donck
> [...]
> <FAQENTRY> DRAFT
> 4.nn How is String Manipulation best done?
>
> The String Object has simple methods such as indexOf; but, especially
> for complex string manipulation tasks, methods using RegExps can be much
> more useful. RegExps allow sought-for structures to be expressed
> compactly.
A beginner has thrown the towel in the ring before the end of that
sentence.
> BOX -----------
> http://docs.sun.com/source/816-6408-10/regexp.htm - RegExp Object
> http://msdn.microsoft.com/library/en-us/script56/html/js56reconIntroduct
> ionToRegularExpressions.asp - ???
> ...?
> ---------------
>
> The first box in *4.16* shows simple usage of String.replace with a
> RegExp literal argument.
>
> BOX -----------
> Example using String.match() - maybe
> function Part(YMD) { // Date components to Array
> return YMD.value.match(/^([+-]?\d+)\D+(\d+)\D+(\d+)$/) }
> Example using /RegExp/.test() - maybe
> if (!/(.*)\s+([a-z]+)/i.test(DTstr.replace(/-/g, "/")))
> return NaN // cannot be Date + Abbr
> Example of var RE = /RegExp/ // and/or new RegExp()
> ---------------
> DRAFT </FAQENTRY>
>
> Now we need a small-country person to rewrite that in simpler English!
I think it's not necessarily a question of simpler English, but a
matter of educational methodology. One aspect is the use of simple
words where possible indeed. But I think the core is to take the reader
by the hand and to explain things step by step.
One of the worst things to do here is to overwhelm with high-level
considerations and long texts; these will cause the reader to quickly
give it up. It's better to write shorter articles with many code
examples, and thus feeding the confidence of the reader.
I will try to demonstrate this principle using test() from your code:
---------------------------------------------------------
You can use test() to check if a variable contains some character(s):
if (/a/.test('abc')) {
alert('"abc" contains "a"'); }
You can also put 'abc' in a variable:
var str = 'abc';
if (/a/.test(str)) {
alert('variable str contains "a"'); }
You can check if "abc" _starts_ with "a":
if (/^a/.test('abc')) {
alert('"abc" starts with "a"'); }
You can check if it contains one or more digits:
if (/\d/.test('x3y')) {
alert('"x3y" contains at least one digit'); }
et cetera.
---------------------------------------------------------
--
Bart
Randy Webb
> Richard Cornford wrote:
>
>> Are you sure you are not trying to solve the wrong problem? ...
>
> As I understand, the main problem is rather content-related and not
> technical.
Then you misunderstand the problem. The problem is that the system that
was being used had an automated posting. That automated posting has now
stopped working so the FAQ doesn't get posted to the group as it should.
> Yes, I'm ready to do some proposals now and then in this newsgroup:
>
> - concise and preferably common problems
> - quality response
> - easy to copy/paste for FAQ maintainer
> - what's already in the archive
All of that already exists and I dare say that you won't find anybody
that can write out better quality explanations of JS related subjects
than Richard Cornford.
--
Randy
comp.lang.javascript FAQ - http://jibbering.com/faq & newsgroup weekly
Javascript Best Practices - http://www.JavascriptToolbox.com/bestpractices/
Matt Kruse
> All of that already exists and I dare say that you won't find anybody
> that can write out better quality explanations of JS related subjects
> than Richard Cornford.
I agree, although 'concise' seems to be a challenge for him ;)
--
Matt Kruse
http://www.JavascriptToolbox.com
http://www.AjaxToolbox.com
Randy Webb
> Randy Webb wrote:
>> All of that already exists and I dare say that you won't find anybody
>> that can write out better quality explanations of JS related subjects
>> than Richard Cornford.
>
> I agree, although 'concise' seems to be a challenge for him ;)
>
I left that word out intentionally :)
Dr John Stockton
Jul 2006 02:40:35 remote, seen in news:comp.lang.javascript, Richard
Cornford <Ric...@litotes.demon.co.uk> posted :
>
><snip>
>> <FAQ**TRY> DRAFT
>> 4.nn How is String Manipulation best done?
>
>I cannot see a blanket statement about how string manipulation is "best
>done" as something that could be addressed in a "quick answer". "Best"
>is far too context related when it comes to working with strings.
It is meant to be the sort of "alleged question" that will lead to the
right people reading the reply.
>> The String Object has simple methods such as indexOf;
>
>Without mentioning the relationship between string primitives and String
>objects? An area that is frequently confused in the minds of novices.
Yes, without mentioning it. You have a strong tendency, in News, to go
into considerable depth of detail, and that is out of place in the FAQ.
Put that detail in a FAQ Note, if you like; and if it is wanted in the
FAQ proper it would be better as an entry such as "How are Primitives
and Objects related?"
<FAQENTRY> The FAQ should have a link to each individual FAQ Note. (The
actual link is not so important as the presentation of the Note
Subject). </FAQENTRY>
>
>> but, especially for complex string manipulation tasks, methods
>> using RegExps can be much more useful.
>
>You cannot say "RegExps" in place of regular expressions. Certainly not
>here, if at all.
Granted that "Regular Expressions" should occur once in the entry. But
"RegExp" is commonly used in News, and "RegExp" occurs in the Javascript
language whereas "Regular Expression" only occurs in descriptions of the
Javascript and other languages.
>> RegExps allow sought-for structures to be expressed
>> compactly.
>
>Is that sentence going to convey meaning?
Ask Bart to re-express the concept! One could put "A regular
expression is a pattern of text that consists of ordinary characters
(for example, letters a through z) and special characters, known as
metacharacters. The pattern describes one or more strings to match when
searching a body of text. The regular expression serves as a template
for matching a character pattern to the string being searched." though
that would breach copyright, as would "A regular expression object
contains the pattern of a regular expression. It has properties and
methods for using that regular expression to find and replace matches in
strings." But the situation does call for brevity. Probably
"patterns" is better than "structures".
><snip>
>> DRAFT </FAQ**TRY>
>
>You may not appreciate it but I have put a great deal of thought into
>how regular expressions should be covered by the FAQ
> ...
Since there has been no visible result, your thought has so far been a
waste of time.
Remember, provided that a FAQ maintainer is prepared to change the
document frequently, the easiest way to acquire a good FAQ entry is to
insert a not-very-good one and amend in accordance with the better
responses.
When I maintained a FAQ, it was (actually, it still is) part of my Web
site, its master being among the masters of the other first-level pages.
Incremental changes could be made in the time it takes to load an editor
window, edit, save; it would be uploaded at my next dial-up. When the
topic was active, someone else CRONned every Sunday morning to copy from
the Web site and post to News.
--
© John Stockton, Surrey, UK. ???@merlyn.demon.co.uk Turnpike v4.00 MIME. ©
Web <URL:http://www.merlyn.demon.co.uk/> - w. FAQish topics, links, acronyms
Dates - miscdate.htm Year 2000 - date2000.htm Critical Dates - critdate.htm
Euro computing - european.htm UK Y2k mini-FAQ: y2k_mfaq.txt Don't Mail News
Dr John Stockton
, dated Mon, 24 Jul 2006 02:58:15 remote, seen in
news:comp.lang.javascript, Bart Van der Donck <ba...@nijlen.com> posted :
>Dr John Stockton wrote:
>
>> [...]
>> <FAQENTRY> DRAFT
>> 4.nn How is String Manipulation best done?
>>
>> The String Object has simple methods such as indexOf; but, especially
>> for complex string manipulation tasks, methods using RegExps can be much
>> more useful. RegExps allow sought-for structures to be expressed
>> compactly.
>
>A beginner has thrown the towel in the ring before the end of that
>sentence.
You're no beginner : you'll see what is meant : so pray re-express the
concept better!
>I will try to demonstrate this principle using test() from your code:
One IMHO should, if the "alleged question" is as general as that which
I've proposed, include an indication of the potency of RegExps. That
could be done in words; but ISTM that it can best be done by the
conjunction of a RegExp-using statement of moderate complexity and a
comment describing what it does, but not how. There's no need for a
newcomer to understand that example at first sight; merely to believe
that he will become able to read & write such.
FAQ RegExp examples should NOT include anything that can be done
perfectly readily with non-RegExp methods; the purpose of a FAQ RegExp
entry must be to persuade newcomers to follow its links and learn more.
Even on my <URL:http://www.merlyn.demon.co.uk/js-valid.htm> "RegExps &
Validation" it's impractical to teach RegExp use without reliance on
outside material.
Randy Webb
> JRS: In article <ea18ek$inm$1$8302...@news.demon.co.uk>, dated Mon, 24
> Jul 2006 02:40:35 remote, seen in news:comp.lang.javascript, Richard
> Cornford <Ric...@litotes.demon.co.uk> posted :
<snip>
>>> but, especially for complex string manipulation tasks, methods
>>> using RegExps can be much more useful.
>> You cannot say "RegExps" in place of regular expressions. Certainly not
>> here, if at all.
>
> Granted that "Regular Expressions" should occur once in the entry. But
> "RegExp" is commonly used in News, and "RegExp" occurs in the Javascript
> language whereas "Regular Expression" only occurs in descriptions of the
> Javascript and other languages.
And you expect someone that is actually using the FAQ to learn something
to understand the jargon used in Usenet? 99% of them can't even find the
FAQ - even though FAQ's are very common in Usenet .
<snip>
>>> DRAFT </FAQ**TRY>
>> You may not appreciate it but I have put a great deal of thought into
>> how regular expressions should be covered by the FAQ
>> ...
>
> Since there has been no visible result, your thought has so far been a
> waste of time.
Do you honestly believe that crap you spouted?
> Remember, provided that a FAQ maintainer is prepared to change the
> document frequently, the easiest way to acquire a good FAQ entry is to
> insert a not-very-good one and amend in accordance with the better
> responses.
Hmmm, so a newbe reading a crappy entry is the best way to maintain an FAQ?
Makes me glad you aren't the FAQ Editor.
Dr John Stockton
Mon, 24 Jul 2006 15:24:44 remote, seen in news:comp.lang.javascript,
Randy Webb <HikksNo...@aol.com> posted :
>Bart Van der Donck said the following on 7/24/2006 4:30 AM:
>> As I understand, the main problem is rather content-related and not
>> technical.
>
>Then you misunderstand the problem. The problem is that the system that
>was being used had an automated posting. That automated posting has now
>stopped working so the FAQ doesn't get posted to the group as it should.
Your understanding, as described above, is inadequate.
There have been three problems.
(1) As you say above;
(2) As you know, although FAQ 8.1 was released, the home site reverted
to FAQ 8.0 (now corrected);
(3) The FAQ is rarely updated.
Additionally, ISTM that the FAQ would benefit from the sort of treatment
that might, for a book, be given by a good sub-editor : re-phrasing and
re-arranging the existing content.
Read the newsgroup FAQ.