-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
1209 lines (1076 loc) · 53.2 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
<title>Notes on the comp.lang.javascript FAQ</title>
<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<link href="../../faq.css" rel="stylesheet" type="text/css">
<link href="../notes.css" rel="stylesheet" type="text/css">
<meta name="ROBOTS" content="NOINDEX, NOFOLLOW">
<style type="text/css">
.resourceList LI {
margin-bottom: 0.8em;
}
</style>
</head>
<body>
<h1>Posting Questions and Replies to comp.lang.javascript</h1>
<div id="faqNav">
<a href="../../">FAQ</a> > <a href="../">FAQ Notes</a>
</div>
<ul>
<li><a href="#ps1Intro">Introduction</a></li>
<li><a href="#ps1Lang">Posting Language</a></li>
<li><a href="#ps1OToc">On and Off Topic Posting</a></li>
<li><a href="#ps1Txt">Plain-Text Only</a></li>
<li><a href="#ps1Post">Interleaved Posting, Bottom Posting and Not Top Posting.</a>
<ul>
<li><a href="#ps1InBPost">Interleaved Posting, Bottom Posting</a></li>
<li><a href="#ps1TopPs">Top Posting (don't)</a></li>
</ul>
</li>
<li><a href="#ps1Trim">What to Trim</a></li>
<li><a href="#ps1Marg">Margins and Line Wrapping</a>
<ul>
<li><a href="#ps1Mar">Margins</a></li>
<li><a href="#ps1Lw">Line Wrapping</a></li>
<li><a href="#ps1LwQu">Line Wrapping in Quoted Material</a></li>
</ul>
</li>
<li><a href="#ps1Code">General Code Postings, and when to use a URL</a></li>
<!-- <li><a href="#ps1Proof">Proof-read your message</a></li> -->
<li><a href="#ps1Quest">Well Asked Questions Get the Best Answers</a>
<ul>
<li><a href="#ps1QSub">Appropriate Use of the Subject Header</a></li>
<li><a href="#ps1QRes">Doing Your Own Research</a></li>
<li><a href="#ps1DontWork">"It doesn't work"</a></li>
<li><a href="#ps1CntX">Explain the Whole Context</a></li>
<li><a href="#ps1PR">Proof-Read your Questions</a></li>
</ul>
</li>
<!-- <li><a href="#ps1notHD">comp.lang.javascript is Not a Helpdesk</a></li> -->
<li><a href="#ps1AddR">Additional Reading</a></li>
</ul>
<h2 id="ps1Intro">Introduction</h2>
<h3>Social Behavior</h3>
<p>
There may be several reasons for making posts to comp.lang.javascirpt
but all valid reasons would be intended to elicit responses, preferably
including responses form the many experienced and knowledgeable
regular contributors to the group. The direction of communication is
always one-to-many, which places the onus on the composer of a message
to consider the many in their audience above any personal preferences.
It is always in the best interest
of someone posting to the group to recognise that the people whose
responses will be of most value to them may have an attitude toward
their behaviour on the group, and to try to ensure that it will not be
a bad attitude.
</p>
<p>
It is also always in the best interest of any poster to the group to do
everything within their power to behave in a way that makes it quick
and easy for the people they expect to answer their questions to read and follow
their posts, understand their questions and problems and comprehend and
test posted code. The people with the best answers are the most likely
to be busy; too busy to be interested in unraveling a badly expressed
problem from a mass of incomprehensibly formatted code amid a
conversation that is hard to follow.
</p>
<p id="ps1Into_3">
Usenet has been around for a long time now and has developed various
conventions of its own. Conventions that have evolved to make
communicating in the medium as easy and efficient as possible. They
are not necessarily adhered to on all groups but where they are
recognised they are definitely preferred. And comp.lang.javascript is
a group where most of the regulars recognise many Usenet conventions
and so the FAQ outlines them. This document is intended to provide
additional detail on the subject.
</p>
<p id="ps1Into_4">
Following those conventions and additionally posting with a
consideration of the other points made on this page related more
specifically to posting in comp.lang.javascript, will maximise the
potential for any questions asked and posts made to elicit a useful
response. At least in part because they make it quicker and easier for
those interested in offering help to do so.
</p>
<h2 id="ps1Lang">Posting Language</h2>
<p id="ps1Lang_1">
comp.lang.javascript is the international javascript group. There are
language specific javascript groups that could be expected to be
carried by news servers within the countries concerned. There is,
however, no English language specific javascript group so
comp.lang.javascript serves that audience. As a result the vast
majority of the conversation within the group is in English, and
anyone with a javascript interest but incapable of reading/writing any
language but English would choose comp.lang.javascript to read and post
in. But there are no rules that say that English is the only language
that is to be used.
</p>
<p id="ps1Lang_2">
As an international group, comp.lang.javascript has contributors form
around the world, many of whom speak/read/write English as a second or
third (+) language. So a post made in any other language will stand a
chance of falling within the linguistic capabilities of someone. But
posts in English should be understandable to everyone, including those
for whom English is their only language, and thus receive the most
attention.
</p>
<p id="ps1Lang_3">
Machine translation into English (and sometimes less skilled human
translation) sometimes does not produce results that can be
understood/followed by English speakers. When a bad translation into
English is the only option it might be better for a poster to precede
it with a version in their native language. (Faced with a post in a
language that is not understood it is natural to scroll down to see
if there is any accompanying javascript code that might explain the
problem; a following English translation would be discovered along
the way). A reader of the group who understands the language used
may be able to contribute improvements to the English translation even
if they cannot directly address the question raised.
</p>
<p id="ps1Lang_4">
However, even though the most common language used in postings to
comp.lang.javascript is English, the fact that the group is
international and that English should not be expected to be the first
language of contributors to the group means that the English used
should be formally correct (to the best of the posters ability).
Normal English sentence structure should be observed, particularly in
terms of capitalisation (which serves to aid reading for everyone). But
above all, shorthand abbreviations should not be used, no matter how
common they may be in English speaking cultures, as they would not
normally be part of the teaching of English as a foreign language. This
applies especially to text-message shorthand as they are very much a
product of local culture and circumstances in a way that is not
relevant to Usenet as a medium or appropriate to an international
newsgroup.
</p>
<p id="ps1Lang_5">
In the context of an international forum it is also probably best to
avoid references that may be ambiguous outside of a national context.
Date formats are an obvious example, with the ISO 8601 <code>YYYY-MM-DD</code> format
being more appropriate than any preferred local form. Also, references
to national bodies by acronym alone will not necessarily convey
sufficient meaning to an international audience.
</p>
<h2 id="ps1OToc">On and Off Topic Posting</h2>
<p id="ps1OToc_1">
ECMA 262 is the formal specification for ECMAScript, the
standard adopted by javascript implementations and thus the
specification for javascript.
</p>
<h3>ECMAScript and Browsers</h3>
<p id="ps1OToc_2">
As comp.lang.javascript deals with ECMAScript and ECMAScript was
designed as a general scripting language for scripting any object
model, questions relating to any application of ECMAScript are
appropriate. The group has a general bias towards the use of
ECMAScript in web browsers in an Internet context, and questions
asked without additional qualification will tend to be assumed to
be related to that environment and context. As a result it is a
very good idea for questions asked that are not related to that
default context; Intranet, other hosts, OS automation, etc., to
include details of that context.
</p>
<h3 id="ps1OToc_3">Javascript (not Java)</h3>
<p>
Because of the name "JavaScript" being applied to the
language early in its existence there is often confusion between
javascript and the Java programming language. The two are distinct
and very different languages. Questions relating to Java programming,
Java Applets, Java Server Pages (JSP), etc., would be better asked in
comp.lang.java.* groups. Only the use of ECMAScript to interact with,
say, Java Applets would be on topic, and then the questions should
relate to the ECMAScript aspect of the problem.
</p>
<h3 id="ps1OToc_4">Other Languages</h3>
<p>
Questions relating exclusively to other scripting languages,
mark-up languages ((x)<span class="initialism" title="HyperText Mark-up Language"><abbr title="HyperText Mark-up Language">HTML</abbr></span>) and style sheets
(<span class="initialism" title="Cascading Style Sheet"><abbr title="Cascading Style Sheet">CSS</abbr></span>, XSL) are off topic and should be addressed to more
appropriate newsgroups.
</p>
<h3 id="ps1OToc_5">The FAQ</h3>
<p>
The comp.lang.javascript newsgroup may also validly become its own
subject, particularly the content and maintenance of the FAQ resources.
But as a subject that is most appropriately raised and discussed by
the individuals who invest their time in the group rather than
passers-by.
</p>
<h3 id="ps1OToc_6">Usenet Behavior (don't)</h3>
<p>
Usenet, and particularly appropriate behaviour on and for Usenet, is
also often raised. This is largely unwelcome but inevitable. Hopefully
this document should contribute to a reduction in that noise by stating
the group's attitude towards Usenet postings in greater detail than can
be accommodated in the FAQ proper.
</p>
<h3 id="ps1OToc_7">Spam (don't)</h3>
<p>
Other things that are off topic for the group include obvious things
like pyramid and get rich quick schemes, commercial advertising (with
some rare exceptions mentioned below), job adverts, spurious
invitations to visit web sites and anything else that might be
reasonably regarded as spam.
</p>
<h3>Announcements</h3>
<p id="ps1OToc_8">
Announcements of product releases and events of particular relevance
to javascript are welcome but, for products no more often than once
pre major release, and for events preferably only once and certainly
not more often than at two month intervals leading up to the event.
Be aware that product announcements (particularly commercial
javascript) are likely to attract reviews, which should not be
expected to be uncritical.
</p>
<h2 id="ps1Txt">Plain-Text Only</h2>
<p id="ps1Txt_1">
Messages are posted in plain-text. There is no requirement for Usenet
newsreader software to recognise, support or display any other
content type, such as <span class="initialism" title="HyperText Mark-up Language"><abbr title="HyperText Mark-up Language">HTML</abbr></span>, and it is felt that messages posted to
comp.lang.javascript should be available to any and all newsreader
software. Any form of attachments are also ruled out.
</p>
<p id="ps1Txt_2">
It has also been observed that while most of the world may be happy
to use the newsreader bundled with their operating system, experts in
various aspects of computing will often go out and acquire software
that they believe superior for the task they have for it. Meaning that
the people best equipped to offer help in the group are also the people
least likely to be using the newsreader that you are familiar with.
The expectation should be that others are using software that conforms
to the applicable standards and not that they are using software with
any particular set of additional or "enhanced" features, no
matter how common they may seem. Plain-text posts will be readable by
everyone, other content types may be subject to more comment on the
inappropriateness of the content type than answers intended to address
the question raised.
</p>
<h2 id="ps1Post">Interleaved Posting, Bottom Posting and Not Top Posting</h2>
<h3 id="ps1InBPost">Interleaved Posting, Bottom Posting</h3>
<p id="ps1InBPost_1">
The posting style in messages intended as responses to other messages
is an area where a long established pattern of behaviour has been
recognised as most appropriate for the medium and become an established
convention.
</p>
<p id="ps1InBPost_2">
Material quoted from the previous message is attributed to its author
and indented with a marker character (usually >). It is trimmed down
to just sufficient to provide the context in which the response is made
(marking the fact that an edit has been made with one of several
common notations, such as: <snip>, [snip], [ ... ], etc.) and
the responding text is placed <em>below</em> the quoted material
to which it is responding, separated from it by a blank line.
</p>
<p id="ps1InBPost_3">
If the response addresses several points from the previous message
then the parts of the quoted text providing the context for each
point are separated by the responses to each point. Producing an
interleaved post. If the quoted material is in one block then the
response text goes after it at the bottom. Producing a bottom post.
</p>
<p id="ps1InBPost_4">
It is not possible to distinguish between bottom posting and an
interleaved post that is only responding to one point in the previous
message. Personally, I prefer interleaved responses but neither will
result in an adverse reaction. The important points are that quoted
material should be trimmed to the minimum that provides sufficient
context and that responses should follow that quoted material.
The conversation, and its chronological sequence, flows in the normal
direction of reading; top to bottom.
</p>
<p id="ps1InBPost_5">
Failing to quote any of the preceding message is not necessarily
wrong, so long as the text posted makes sense without the preceding
message, for example, by summarising the points being responded to.
But generally it is easier to provide the context for a response with
a quoted snippet. But responses need to have a context.
</p>
<h3 id="ps1TopPs">Top Posting (don't)</h3>
<p id="ps1TopPs_1">
Top posting is placing the response above the quoted material that is
being responded to. The chronological sequence of conversation becomes
the reverse of the normal top to bottom reading sequence and, without
additional text summarising the points being responded to, it is
difficult to determine exactly which points such a reply relates to.
</p>
<p id="ps1TopPs_2">
The worst possible style of response posting is top posting over a full
verbatim quote of the previous message, but even placing a response
above a trimmed quote is wrong. It renders the conversational aspects
of a response backwards, requiring people to scroll up and down to
reconstruct the context of the response and generally making it hard
work to understand the message. The answers come before the questions
and the comments precede their subjects.
</p>
<p id="ps1TopPs_3">
People do attempt to justify top posting. A common excuse made by top
posters is that their newsreader places the cursor at the top of the
message so that is the natural place to write the reply. That excuse
is worthless as newsreader software does not dictate the style of
posting and a cursor that starts at the top of a post does not have
to stay there. Indeed it should not be expected to stay there, as the
first responsibility of the respondent is to trim the quoted material
down to just what is necessary to provide context for their response.
A process that may reasonably be achieved by moving down through the
quoted material deleting whatever is unneeded and marking those edits.
And having done that the cursor will be at or near the bottom.
</p>
<p id="ps1TopPs_4">
The other common excuse for top posting is that avoids excessive
scrolling in order to find the response. The need for excessive
scrolling in an interleaved or bottom posted message is most likely
an indicator that the quoted material has not been suitably, or
sufficiently, trimmed. But a top posters apparent desire to avoid
scrolling is of no value to the regular users of Usenet who are
accustomed to interleaved/bottom posting. They may take the top
post as a preamble and still scroll down to see if any specific
points have been responded to, not discovering that hey have wasted
their time until they get to the bottom. A very short top post,
without a blank line separating it from the following attribution
line, may easily be missed by someone expecting the quoted material
to come first, meaning that they do not discover where to look until
they have scrolled to the bottom, and then they need to back scroll
to the top. The perception is wrong, top posting results in much more
unnecessary scrolling than it avoids, and that misperception impacts on
regular user of Usenet; the very people whose help and co-operation is
being sought.
</p>
<p id="ps1TopPs_5">
<strong>Never top post to comp.lang.javascript</strong>. There is an
established convention in posting styles on Usenet, and
comp.lang.javascript. It is most efficient for everyone if newcomers
follow that convention even if it seems strange to do so at first. In
the long run it makes life easier for everyone, and the sooner that is
recognised the less likelihood there is of being taken for a fool.
</p>
<h2 id="ps1Trim">What to Trim</h2>
<p id="ps1Trim_1">
As a general guide, quoted material should almost never exceed the
text posted in response. Exceptions might occur when both consist
of exactly one line or sentence, or maybe a short code block that
only needs a one line comment.
</p>
<p id="ps1Trim_2">
Deciding what to trim is a matter of judgment and takes a bit of
practice to get right. There are few hard and fast rules and the best
general advice has got to be to observe the behaviour of others
positing to the group.
</p>
<p id="ps1Trim_3">
It is necessary to preserve the context in
which a response is made but some things can be trimmed automatically:
Signatures (if present); the section at the end of a post (and they
should always, and only, be at the end, no matter where any individual
newsreader may try to insert them) which starts with a separator
consisting of "dash dash space newline(aka return)" on a
line of its own, followed by material that is not directly
related to the post but may be of more general interest or related
to the individual who makes the post, should <strong>always</strong>
be trimmed from quoted material. It is never normally relevant to a
posted response, but even if a signature is being directly commented
upon it is vital to remove the signature separator at least, and best
to trim anything it contains that is not being commented upon.
</p>
<p id="ps1Trim_4">
In comp.lang.javascript there is rarely much point in quoting
javascript code that is not being directly commented upon or
corrected. The indenting character (and possible line wrapping)
renders any quoted code syntactically invalid so anyone wanting
to use the code will have to go back to the message in which it
originally appeared anyway. That would certainly apply to a post
wishing to thank someone who had provided a complete scripted
demonstration for their efforts.
</p>
<p id="ps1Trim_5">
No matter what gets trimmed the material that stays should not be
altered in terms of spelling, words used and their order, etc. A
quote should be a quote not an interpretation.
</p>
<h2 id="ps1Marg">Margins and Line Wrapping</h2>
<h3 id="ps1Mar">Margins</h3>
<p id="ps1Mar_1">
A line in a plane text Usenet post could be quite long, and some
newsreaders would automatically wrap that line to the window in
which it was being displayed. Others would provide horizontal scroll
bars (usually undesirable) and yet others may not be able to access
characters beyond the 80<sup>th</sup> (unlikely these days). There
are no rules for handling excessively long lines but Usenet is old
and has lived through the time when 80 character wide displays were
commonplace. Along the way it became the convention that Usenet posts
should have lines no longer than between 70 and 80 characters. And
that avoids the need for any specified requirement in the handling of
long lines by newsreader software. Lines in that range are unlikely to
need to be wrapped for display and will not normally generate
horizontal scroll bars. It is also the case that humans generally
(and sometimes strongly) prefer to read text that is no more than about
80 character per line.
</p>
<p id="ps1Mar_2">
It is widely recommended that newsreader software should be configured
to automatically wrap at about 72 characters when posting, which works
well for posted text but can be problematic for posting long URLs and
particularly in our context, posted source code. Others suggest that
software should not be allowed to wrap posted code at all and that the
poster should always do it manually. In either case it is the
individual composing the post that is responsible for, and should be in
control of, the wrapping of the content to ensure that it is suitable
for posting to the group.
</p>
<h3 id="ps1Lw">Line Wrapping</h3>
<p id="ps1Lw_1">
Most URLs are less than 72 character long anyway but some, such as
references to Usenet articles in the archives at groups.google.com,
are longer. Some newsreader software is smart enough to recognise a
URL and not apply its default margin settings to them but in any event
delimiting them with "<URL:" at the beginning and
">" at the end (preferably with the URL separated from
the delimiters with spaces) should be sufficient to indicate to a
reader that a line wrapped URL will need some remedial action.
</p>
<p id="ps1Lw_2">
Restricting margins to 72 characters usually does not need to affect
the functionality of posted code either. Allowing a newsreader to
line wrap posted code as it sees fit will usually render that code
faulty (and difficult to read) and that will make it difficult for
a reader to differentiate between problems within the original code
and problems arising form line wrapping.
</p>
<h3 id="ps1Lw_3">Code Reformatting</h3>
<p>
Javascript (ECMAScript) is extremely tolerant of white space (including
line breaks) within its source code. There are in fact only a couple of
places where white space characters are not allowed. For example, a
line break may not be placed between the <code>return</code> keyword
and any expression that is to be returned. As a result it is almost
always possible to spread a line of javascript that would exceed the
newsreaders wrapping margin across two or more lines without affecting
its functionality or syntactic correctness.
</p>
<p id="ps1Lw_4">
One of the main reasons that Javascript is so tolerant of white space
is to allow the structure of the source code (how the code is laid out
in a text editor/post) to convey additional meaning (usually related to
structure of the code/function/program) and maximise clarity for human
readers. The breaking of long lines of source code across several lines
should be done in a way that does not detract from the clarity of the
code.
</p>
<h4 id="ps1Lw_5">Blocks</h4>
<p>
The main source code structuring consideration that adds clarity is
block indenting. A block is defined with curly brackets <code>{</code>
and <code>}</code> and represents a block statement (which may contain
zero or more other statements). It is normal to indent the statements
within a block by one tab character, though that tab is usually set to
4 or fewer spaces (two spaces is frequently recommended) width as the
normal default 8 spaces width is a bit
too deep for most practical uses. However, <em>tab character should not be
used for indention in Usenet posts at all</em> as newsreader default tab
settings may often be 8 characters but may also be zero characters,
defeating the purpose indentation in posted code entirely. Good text
editors will usually offer a facility to convert tabs to any number of
spaces, which can be used to prepare code for posting. Indenting in
code posted to Usenet should be done with space characters. 4 or fewer
(two is often recommended) per level of indentation.
</p>
<p id="ps1Lw_6">
There are various common styles of block indenting, of which I prefer
to leave the opening <code>{</code> at the end of the control statement
(on the same line) and list the block contents as one statement per
line, indented by 4 <em>or fewer</em> spaces, with the closing
<code>}</code> on a new line indented so that it lines up vertically
with the start of the control statement, e.g.:-
</p>
<pre id="ps1Lw_ex1">
function doSomething(oArea){
var nArea = oArea.nWidth * oArea.nHeight;
var result = true;
if(!nArea){
removeRegion(oArea);
result = false;
}else if(oArea.nWidth < oArea.nHeight){
result = oArea.reShape(nArea);
}
return result;
}
<span class="commentJS">/* The same function may also be commonly formatted:- */</span>
function doSomething(oArea)
{
var nArea = oArea.nWidth * oArea.nHeight;
var result = true;
if(!nArea)
{
removeRegion(oArea);
result = false;
}
else if(oArea.nWidth < oArea.nHeight)
{
result = oArea.reShape(nArea);
}
return result;
}
<span class="commentJS">/* -or:- */</span>
function doSomething(oArea)
{
var nArea = oArea.nWidth * oArea.nHeight;
var result = true;
if(!nArea)
{
removeRegion(oArea);
result = false;
}
else if(oArea.nWidth < oArea.nHeight)
{
result = oArea.reShape(nArea);
}
return result;
}
</pre>
<p id="ps1Lw_7">
It is not that important which style of block indenting is used,
everyone has their own preferred style, but it is important that
<em>a</em> style of block indenting is used in code posted to the
group. In all cases the indenting serves to make the structure of
the function apparent in the structure of the source code. It is
an aid to human readers of the code and saves a great deal of time
for anyone attempting to offer help and so needing to understand
the code.
</p>
<p id="ps1Lw_8">
Sometimes the line wrapping problem can be avoided by reducing the
number of space characters by which the blocks are indented. However,
if a statement must be broken across several lines
it could be indented to a different level than it's own start, and it
could also be indented at a different level to its block contents (if
any). If block indenting is at, say, 4 space intervals then indenting a
broken line at 1 to 3 characters should serve to make it clear that
it is indenting separate from the general block structure of the
code, e.g.:-
</p>
<pre id="ps1Lw_ex2">
function getRootElement_OrDefault(deflt){
if((typeof document.compatMode == "string")&&
(document.compatMode.indexOf("CSS") != -1)&&
(document.documentElement)){ <span class="commentJS">//<< broken statement</span>
return document.documentElement;
}else if(document.body){
return document.body;
}else{
return deflt;
}
}
</pre>
<p id="ps1Lw_9">
Another alternative for formatting statements broken across lines
might be to disregard the indenting on the left and line the code
that belongs to the broken statement up on the right hand side.
e.g.:-
</p>
<pre id="ps1Lw_ex3">
this.position = function(){
var twiceSize;
if(--delay <= 0){
step();
if(((z+=fv) >= planeDepth)||
((dy+dm) > windowCenterY)||
((dx+dm) > windowCenterX)||
(v < 0)){ <span class="commentJS">//right aligned broken statement</span>
this.reset();
step();
}
div.top = (sy+(py*dy)-dm)+cssUnitsOrZero;
div.left = (sx+(px*dx)-dm)+cssUnitsOrZero;
divClip.height = (twiceSize = (dm << 1)+cssUnitsOrZero);
divClip.width = twiceSize;
}
next.position();
};
</pre>
<p id="ps1Lw_10">
Thus the ability to insert line breaks liberally throughout javascript
source code allows almost all code to be formatted in a fully
functional, well structured and clear way within the restricted
margins appropriate in posts to comp.lang.javascript. Efforts put into
preparing posted code to be clear and comprehensible to its Usenet
audience will be rewarded. But it is important to start any formatting
required with the actual code in use, rather than attempting to
re-type it, in order not to introduce errors that are not present in
the original and so have nothing to do with the original problem.
Having prepared the formatting of the code to suite Usenet it is
important to re-test it to ensure that it is still as functional, that
no errors have been introduced and that it still exhibits whatever
behaviour it was that motivated the post in the first place.
</p>
<h3 id="ps1LwQu">Line Wrapping in Quoted Material</h3>
<p id="ps1LwQu_1">
If a news post has been wrapped at, say, 72 characters and it is
responded to then the indenting character used to mark quoted material
will add to the length of that line. Maybe pushing it over the length
at which the reply will be wrapped. The result, if posted without
adjustment, may look something like this:-
</p>
<pre id="ps1LwQu_ex1">
An example OP wrote:
> A long line of text quoted from the previous post, that was wrapped
at
> 72 characters in that post but has been extended to 74 characters
long
> lines because of the addition of the indenting characters that mark
it
> as a quotation, but has been re-wrapped to 72 characters in the
posted
> follow-up that is quoting it.
The comment posted in response to the material quoted above. Originally
wrapped in the response at 72 characters.
</pre>
<p id="ps1LwQu_2">
The effect is that the words "at", "long",
"it" and "posted" are no
longer marked as part of the quotation but instead appear to be badly
formatted and meaningless comments on that quoted material. Which has
itself gained the appearance of being incompetently trimmed. The effect
escalates with additional responses, loosing more meaning and becoming
less and less clear as to whom any particular part of the text is
attributable.
</p>
<pre id="ps1LwQu_ex2">
The First Responder wrote:
> An example OP wrote:
>> The First Responder wrote:
>>> An example OP wrote:
>>>> A long line of text quoted from the previous post, that was
wrapped
>>> at
>>>> 72 characters in that post but has been extended to 74 characters
>>> long
>>>> lines because of the addition of the indenting characters that
mark
>>> it
>>>> as a quotation, but has been re-wrapped to 72 characters in the
>>> posted
>>>> follow-up that is quoting it.
>>>
>>> The comment posted in response to the material quoted above.
>> Originally
>>> wrapped in the response at 72 characters.
>
>> This response is the OP's reply to the comments on the original
>> post. It quoted the previous posts in full and was wrapped at 72
>> characters.
>
>And the original responder added this.
The conversation ended with the OP thanking the responder for their
comments. (but who said what?)
</pre>
<p id="ps1LwQu_3">
The solution is to be aware that this may happen and re-wrap that
quoted material so that it is not effected by the automatic line
wrapping when a post is sent, or to increase the wrapping margins by
the number of characters inserted to mark a quotation (so long as the
result does not exceed 80 characters). Some newsreader software can
handle this automatically, and add on software exists for other
products (such as OE), but ultimately the responsibility for properly
marking and attributing quoted material belongs with the individual
making the post.
</p>
<p id="ps1LwQu_4">
If the two had taken the effect of the progressive lengthening of lines
in quoted material into account the result would have looked like
this:-
</p>
<pre id="ps1LwQu_ex3">
The First Responder wrote:
> An example OP wrote:
>> The First Responder wrote:
>>> An example OP wrote:
>>>> A long line of text quoted from the previous post, that was
>>>> wrapped at 72 characters in that post but has been extended to 74
>>>> characters long lines because of the addition of the indenting
>>>> characters that mark it as a quotation, but has been re-wrapped to
>>>> 72 characters in the posted follow-up that is quoting it.
>>>
>>> The comment posted in response to the material quoted above.
>>> Originally wrapped in the response at 72 characters.
>
>> This response is the OP's reply to the comments on the original
>> post. It quoted the previous posts in full and was wrapped at 72
>> characters.
>
>And the original responder added this.
The conversation ended with the OP thanking the responder for their
comments.
</pre>
<p id="ps1LwQu_5">
It would have been clear form the number of quote indicating characters
who exactly had said what and the quoted material would have been
easier to read and understand. Though in practice there probably should
have been much more trimming along the way as the whole conversation
would probably not have been needed to show the context of each
response.
</p>
<h2 id="ps1Code">General Code Postings, and when to use a URL</h2>
<p id="ps1Code_1">
Often a question cannot usefully be answered without being accompanied
with javascript source code. Even a very detailed explanation of a
process will not tend to narrow the possibilities down to just one
method, and deciding whether a reported effect is due to a
characteristic of an execution environment or code that is taking the
wrong approach cannot be done without seeing the source code.
</p>
<p id="ps1Code_2">
In some cases small snippets of code, say an individual function's
definition, might be sufficient. Though it is usually necessary to know
how such a function is being called and what arguments it is using. But
ideally questions should be accompanied by an easily testable example
that demonstrates the characteristics that provoked the question.
</p>
<p id="ps1Code_3">
Easily testable because there is no better aid to debugging than being
able to reproduce a problem. Time spent turning a snippet of code into
testable web page (or whatever) is not rewarded if the results do not
exhibit the problem described. And asking many people to repeat that
process when it could have been done by the questioner once, in a way
that guaranteed a demonstration of the problem, is not a good use of
the group or the time of its participants.
</p>
<p id="ps1Code_4">
However, posting the entire source code of a web page that happens to
include the problematic script is rarely the answer. For one thing web
pages often import <span class="initialism" title="Cascading Style Sheet"><abbr title="Cascading Style Sheet">CSS</abbr></span>, other script files and graphics (the latter
simply could not be posted to the group). But web pages also often
consist of large amounts of <span class="initialism" title="HyperText Mark-up Language"><abbr title="HyperText Mark-up Language">HTML</abbr></span>, which would require careful
re-wrapping to fit within the posting margins and be left correct, and
much of the <span class="initialism" title="HyperText Mark-up Language"><abbr title="HyperText Mark-up Language">HTML</abbr></span> would be irrelevant to the post.
</p>
<p id="ps1Code_5">
There is also the question of bandwidth in transmission and capacity in
storage. Every post is stored, at least for a time, on every news server
carrying the group world wide and usually also on the hard disk of
everyone who reads the group. And to get from server to server, and
eventually to the many readers, it must be transmitted, consuming
bandwidth related to the size of the post. The more irrelevant
information that any post contains the more those resources are wasted
(this is also a reason for appropriate trimming of quoted material).
</p>
<p id="ps1Code_6">
The comp.lang.javascript FAQ makes the injunction that posting code of
more than 500 lines is unacceptable. That is the theoretical upper
limit that should never be exceeded, but a post of even half that
length would have to be exceptional.
</p>
<p id="ps1Code_7">
The easiest way of demonstrating a problem in context without posting
excessive amounts of code and <span class="initialism" title="HyperText Mark-up Language"><abbr title="HyperText Mark-up Language">HTML</abbr></span> is to make a page that exhibits the
problem available online and post the URL of that page along with the
question. Possibly accompanied by a snippet of the code highlighting
the suspected cause.
</p>
<p id="ps1Code_8">
The circumstances under which making a page that demonstrates the
problem available online is advisable are, whenever that page is
interacting within a frameset, or whenever images play a significant
part in a problem. As those circumstances are time consuming to
reproduce from posted code and cannot always be recreated for testing.
But any request to have people examine excessive amounts of code
and/or <span class="initialism" title="HyperText Mark-up Language"><abbr title="HyperText Mark-up Language">HTML</abbr></span> should also be made available on line instead of in a post.
</p>
<p id="ps1Code_9">
Unfortunately not all participants in the group are viewing Usenet in a
way that makes easily following a URL to an example page viable. Often
downloading new Usenet posts as a batch and then viewing them off line.
Re-connecting to view an example page is not always desirable (due to
local conditions, slow modem connections and potential associated
expense) and can be unrewarding if the page viewed is a mush of <abbr title="What You See Is What You Get">WYSIWYG</abbr>
generated bloated <span class="initialism" title="HyperText Mark-up Language"><abbr title="HyperText Mark-up Language">HTML</abbr></span>-like noise. Where it takes a considerable time
to even locate the cause of what may still turn out to be a trivial
problem.
</p>
<p id="ps1Code_10">
Then again there are people using the group who much prefer examples to
be available online. Either way what is not wanted is for questions to
be asked without making the corresponding code available in some way,
or the posting of excessive amounts of code.
</p>
<p id="ps1Code_11">
A good compromise, and a valuable debugging technique, is the creation
of a demonstration test-case page. A page containing no more than
sufficient <span class="initialism" title="HyperText Mark-up Language"><abbr title="HyperText Mark-up Language">HTML</abbr></span> and javascript to allow others to reproduce the problem
and see the relevant code without anything extraneous. Such a test-case
page would almost always be short enough to post with the question
(properly formatted) and could additionally be made available online for
the convenience of those that would prefer to use a URL to load it
directly into a browser for testing.
</p>
<p id="ps1Code_12">
Creating such a test-case page can be valuable in itself as attempting
to reduce a problem from a larger context to an isolated demonstration
will often reveal the cause of that problem along the way. The act of
cutting out what initially seems irrelevant often reveals that the
problem in fact results form an unexpected interaction with something
that was assumed to be unconnected. And if the problem can be
demonstrated in isolation then it is relatively easy for readers of the
question to reproduce the problem and identify its cause, resulting in
less discussion of superfluous issues and usually a quicker resolution
of the question.
</p>
<p id="ps1Code_13">
It is very important to test test-case pages prior to posting them to
ensure that they do indeed exhibit the characteristic that motivated
the question. At least if you want to be taken seriously in future. And
when such a test-case is posted to the group it should be formatted and
indented to facilitate the essayist reading of the code and testing by
no more than copying the page into a text editor and saving it locally
as a <span class="initialism" title="HyperText Mark-up Language"><abbr title="HyperText Mark-up Language">HTML</abbr></span> file.
</p>
<h2 id="ps1Quest">Well Asked Questions Get the Best Answers</h2>
<p id="ps1Quest_1">
Beyond any considerations of posting style and formatting, the quality
of questions asked has a considerable impact upon the number and
quality of answers given, and the time taken to elicit a useful
response. Vague questions are likely to be answered with requests for
clarification. Terse general questions are likely to elicit yes or no
answers (often both). And questions that have been asked, and well
answered, before (especially frequently or in the recent past) are as
likely as not to be ignored.
</p>
<p id="ps1Quest_2">
When asking a question it would almost always be a good idea to put
yourself in the position of the reader of the question, read it back to
yourself and ask yourself; Does this question actually ask what I
want to know, and is it sufficiently clear and detailed to elicit that
answer?
</p>
<p id="ps1Quest_3">
The following is a short list of recurring features of badly asked
questions:-
</p>
<h3 id="ps1QSub">Appropriate Use of the Subject Header</h3>
<p id="ps1QSub_1">
Another Usenet convention holds that the Subject header should not be
expected to be available to a reader of any message. While it is
unlikely that there are any newsreaders currently in use in which the
user is not presented with the Subject header, it remains
inappropriate to ask a question in the subject header (or to assume
that its contents will provide supplementary information about a
question) and doing so is as likely to invoke a lesson in Usenet
etiquette as an answer to the question. But a question is not really
a subject anyway. The subject should describe what the question is
in relation to, and is useful for archive searching and
categorisation rather than as a means of communication.
</p>
<p id="ps1QSub_2">
Any question asked should always appear in the body of the post, and in
a form that does not assume the availability of the Subject header to
the reader.
</p>
<p id="ps1QSub_3">
The Subject header should also not be wasted. Placing "please
help" and the like in the subject header is unwelcome and
counterproductive. Take the opportunity to construct a Subject
header that states the type of the problem, what it relates to.
Subject headers that state the real subject will attract the
attention of people with a special interest in that subject,
exactly those people best able to offer help.
</p>
<h3 id="ps1QRes">Doing Your Own Research</h3>
<p id="ps1QRes_1">
Many questions, at least the questions literally asked, could quickly
be answered with a little research, and the chances are that regulars
on the group know how easily those answers could have been found with
a little effort. The group is not intended to be a vending machine for
trivial information about javascript, that wouldn't be an interesting
group to participate in.
</p>
<p id="ps1QRes_2">
On the other hand, evidence that some effort has been put into
researching a problem before asking a question tends to be looked upon
kindly (though claiming to have exhausted all lines of research when that
is obviously not the case would have the opposite effect).
</p>
<p id="ps1QRes_3">