Write a FAQ for Web authors

VERIFIED FIXED

Status

P3
normal
VERIFIED FIXED
18 years ago
16 years ago

People

(Reporter: hsivonen, Assigned: hsivonen)

Tracking

Details

Attachments

(1 attachment, 9 obsolete attachments)

(Assignee)

Description

18 years ago
We need a FAQ for Web authors. Initial draft coming up.
(Assignee)

Comment 1

18 years ago
Created attachment 20526 [details]
First draft

Comment 3

18 years ago
Adding dbaron to cc list.

Comment 4

18 years ago
What they need is examples, because FAQ's are just copies of W3C doc's. So
direct them to a validator for HTML and CSS validation. And then again, where to
locate examples? I did a little search, and it seems that good working example's
for DOM 0/1/2 (and CSS) are very hard to locate. If you provide this kind of
information, that's exactly what web authors need.

And just redirecting them to ECMA and/or W3C is a start, but that's not more
than that.  Or are you ready for this one: "just take a look at 'the garbage' of
other web authors".

Friendly, HJ.
(Assignee)

Comment 5

18 years ago
Created attachment 20750 [details]
Second draft with links
Some quick comments:

Numbering would be nice.  I'll assume it's there. :-)

#1) Once the mode deciding code is improved (hopefully RSN...), I'd like to
reword this.  What we really want to do is use the DOCTYPE as a heuristic to
indicate new vs. old documents, but still allow authors an authoritative way to
override that heuristic.  It would also be good to briefly explain the intent of
the two modes:  quirks mode differs from standards mode where implementing the
standards correctly would break significant numbers of existing pages.

#2) I'd like to provide more details on this one in the future...

#3) It seems to me all the points other than the first two should be sublists
under the first two, except for 7, 10, and the last two, which deal with XML (is
there a good online XML validator?  And does <link /> work in XML?  (Should it?
-- see my comments on other bugs.)).
(Assignee)

Comment 7

18 years ago
Created attachment 20777 [details]
Third draft
(Assignee)

Comment 8

18 years ago
* Added hard-coded numbering (Mozilla doesn't support CSS outline numbering yet)
* Moved some list items into sublists
* Fixed a typo

"instead or <link />" was a typo. I meant "instead of". <link /> does not work with text/xml 
content. I'm inclined to believe it should not work with text/xml, but I am not 100% sure.
(Assignee)

Comment 9

18 years ago
Created attachment 21458 [details]
Fourth draft with two new questions

Comment 10

18 years ago
For Quirks vs. Standard, you need to include
  - the fact that XML is always rendered Standard
  - how to use Quirks with a validating HTML document
henris: feel like sprucing this up? We might need it reasonably soon...

Gerv

Comment 12

17 years ago
Fyi---Ellen Evans (adding to cc list) is writing about XSLT support, and should
have a draft available soon.
(Assignee)

Comment 13

17 years ago
Created attachment 46718 [details]
Fifth draft
(Assignee)

Comment 14

17 years ago
New version attached.

fantasai, I don't think telling how to validate quirky docs is appropriate. That
would make it look like activating the quirks mode was desirable. I think the
message should be that the standards mode is the way to go if you have come far
enough to read the FAQ.
(Assignee)

Comment 15

17 years ago
Can anyone come up with question that are not yet answered but should be?

Should I change to links that point to ekrock's old pages to links pointing to
other mozilla.org docs? If so, which ones?
(Assignee)

Comment 16

17 years ago
Created attachment 46882 [details]
Sixth draft with minor fix (tag vs. element)
> The Quirks mode mimics the behavior of Netscape Navigator 4.x

And some IE quirks, I think. How about "version 4 browsers"?

> * Class names and ids are case-sensitive.

...in standards mode.

> propriertary

proprietary.

> Also, please remember to not use an outdated client sniffer to shut out new 
> browsers.

Link to the ultimate client sniffer?

> layout can be changed by explicitly setting

Why not give explicit sample code that changes all images to "block"?

Eric Krock's page should have internal anchors; you might want to use them for
your two links. And perhaps a few websites under the Further Information link
wouldn't go amiss.

Gerv


The Quirks mode should only mimic IE5/Nav4 when doing so is needed to get
significant numbers of real pages to display correctly.  Otherwise it should
also stick to standards.
(Assignee)

Comment 19

17 years ago
>> The Quirks mode mimics the behavior of Netscape Navigator 4.x
>And some IE quirks, I think. How about "version 4 browsers"?

I don't like "version 4 browsers". It implies that there are only the two (you don't mean Opera 4, right? :-). It 
also implies that browser version numbers are commensurable.

How about "legacy browsers"?

>> * Class names and ids are case-sensitive.
>...in standards mode.

I'd rather not emphasize that.

>> propriertary
>proprietary.

OK.

>> Also, please remember to not use an outdated client sniffer to shut
>> out new browsers.
>Link to the ultimate client sniffer?

I'd rather not point people to a script that assumes some fixed set of existing browsers. I think standard-
compliant script should be fed to any browser that advertises the existence of the applicable DOM objects--
regardless of the name of the browser.

>> layout can be changed by explicitly setting
>Why not give explicit sample code that changes all images to "block"?

I guess making all images blocks is usually harmless--but may not always be. It would also fail to change the 
surrounding <a>s to blocks.

Perhaps something like http://www.hut.fi/u/hsivonen/standards#the-solution or a link pointing there?

>Eric Krock's page should have internal anchors; you might want to use 
>them for your two links. 

OK. BTW, are there similar actively maintained docs at www.mozilla.org?
(Assignee)

Comment 20

17 years ago
I renamed the anchor on my page. It is more descriptive now:
http://www.hut.fi/u/hsivonen/standards#img-display-block
> I'd rather not point people to a script that assumes some fixed set of 
> existing browsers.

It doesn't totally; it sets vars like ie5up and ns6up which you can use for
forwards compatibility. Getting people to use that is far, far better than them
writing their own.

> Perhaps something like

Yes :-)

> BTW, are there similar actively maintained docs at www.mozilla.org?

I wish. Hopefully in the new world.

Gerv

(Assignee)

Comment 22

17 years ago
Created attachment 55765 [details]
Seventh draft
(Assignee)

Comment 23

17 years ago
Sorry for the delay.

>> I'd rather not point people to a script that assumes some fixed set of 
>> existing browsers.

>It doesn't totally; it sets vars like ie5up and ns6up which you can use for
>forwards compatibility.

That still contains the assumption that there are two browsers and that the
identity of the browser is more important than the DOM methods it implements.
What about Opera or Konqueror (or iCab and OmniWeb if they ever implement the DOM)?

(Check out http://www.hut.fi/~hsivonen/test/dom/show-hide-combined-text-js.html
for a show/hide "layer" implementation that supports three object models and
doesn't check for the browser name.)

Are we otherwise in agreement over the FAQ content?

Comment 24

17 years ago
Re:
>Also, please remember to not use an outdated client sniffer to shut out new 
>browsers.

Whatever the merits of types of sniffing, the syntax on this sentence could use
some help.  As it is written, it could be parsed to mean that one shouldn't use
an outdated sniffer only in the case that one wished to shut out new browsers.
Probably the simplest answer would be to place the main clause in the
affirmative:    "Also please remember that outdated client sniffers may shut out
new browsers, so be sure to use an up-to-date one."   Or something along those
lines.

As to XSLT support:  at the moment the processor is not fully compliant,
although they are working on it.  A document indicating what is and is not
implemented is in the final review stages and will soon be up DevEdge.
> * Class names and ids are case-sensitive.

... in standards mode.

> Also, please remember to not use an outdated client sniffer to shut out new 
> browsers.

After you reword this sentence, how about linking to a suitable client sniffer?

Other than that, great. I want to see this on www.mozilla.org ASAP :-)

Gerv

(Assignee)

Comment 26

17 years ago
Created attachment 56748 [details]
Eight draft
(Assignee)

Comment 27

17 years ago
I mentioned that the support for XSLT is imcomplete. I also clarified the JS
client sniffer part and added a simple code sample there. I didn't add a link to
a client sniffer, though, because I think checking for the browser identity as
opposed to browser features goes against the point of having a standard.

There are already sites that let only Netscape 6 execute DOM code. Let's not
encourage that kind of behavior.
> if(document.getElementById) {
>   /* code that uses document.getElementById() */
> }

AIUI, this will cause JS Strict errors. Is "if (getElementById in document)"
supported in enough browsers to be usable as an alternative?

Gerv
(Assignee)

Comment 29

17 years ago
Yes, if(document.foo) causes a strict warning (but not an error). What's the
meaning of the warning? Does it mean "This might be a problem if you didn't do
it on purpose." or does it mean "No, no, don't do that in any case."?

If I use (getElementById in document) in an expression where I'd normally use
(document.getElementById), I get a JS error in Mozilla and the script stops
executing.
Don't let this tiny thing hold up the publishing of this :-) It's not worth
worrying over.

Gerv
(Assignee)

Comment 31

17 years ago
Created attachment 57640 [details]
Check-in-ready version

Attached an unstyled version without the "draft" markings. Fixed one typo and
replaced "PIs" with "processing instructions". Added a link to
http://www.mozilla.org/docs/web-developer/quirks/

Gerv, May I bother you with the check-in? (What would be the correct location?
http://www.mozilla.org/docs/web-developer/faq.html perhaps?)
Attachment #20526 - Attachment is obsolete: true
Attachment #20750 - Attachment is obsolete: true
Attachment #20777 - Attachment is obsolete: true
Attachment #21458 - Attachment is obsolete: true
Attachment #46718 - Attachment is obsolete: true
(Assignee)

Updated

17 years ago
Attachment #46882 - Attachment is obsolete: true
Attachment #55765 - Attachment is obsolete: true
Attachment #56748 - Attachment is obsolete: true
(Assignee)

Comment 32

17 years ago
Comment on attachment 57640 [details]
Check-in-ready version

Oops. A couple of markup error there. This is embarassing.
Attachment #57640 - Attachment is obsolete: true
(Assignee)

Comment 33

17 years ago
Created attachment 57644 [details]
Really a check-in-ready version

Markup errors fixed.
Checked in at the URL suggested. I'll leave it up to you to post to the
newsgroups to advertise its existence.

Gerv
Status: NEW → RESOLVED
Last Resolved: 17 years ago
Resolution: --- → FIXED
I added it to the web developer docs index, and I changed the section name from
"Miscellaneous" to "Writing for Mozilla" since that's what it was.  I'm also
wondering whether to move that section up to the top...
(Assignee)

Comment 36

17 years ago
Thank you. I posted to n.p.m.general and .documentation.

Comment 37

16 years ago
v
Status: RESOLVED → VERIFIED
You need to log in before you can comment on or make changes to this bug.