In article <[EMAIL PROTECTED]>, fantasai <[EMAIL PROTECTED]> wrote:
> http://fantasai.tripod.com/Mozilla/2003/doc-style/guide.html > So, comments are welcome. I suspect Henri has something to say about > charsets? And Boris, do you want <meta> keywords/description in there? Great job. I'm commenting on the things I disagee with. | Use <a name="anchor-name">. Linking to an ID isn't supported | in many browsers. Also, anchors should, like filenames, be | lower case. Links to ids works just fine in contemporary browsers (including Mozilla). Do we really want *require* '<a name="anchor-name">' cruft in docs aimed at people who are supposed to be using primarily Mozilla (eg. in Mozilla developer docs)? | Anchors should not be empty. They should enclose some relevant | fragment of text. For example, place the anchor tags around the | full text of a heading to create an anchor for that section. If | this is done right, highlighting all anchors' text can be a | meaningful and useful styling. More often in practice such anchors get styled as links which isn't cool at all. Depends on the style sheet in use, of course. | Use Latin1. Don't use Windows-specific characters like | open/close double-quotes or long-dash. Don't use Mac-specific | characters either. Make sure all characters you use are | ISO-8859-1, AKA Latin1. Suggested replacement: <li><p><strong>Use the ISO-8859-1 aka. Latin-1 character encoding.</strong> Represent characters that are outside the ISO-8859-1 repertoire (eg. typographically correct dashes and quotes) as decimal numeric character references. For example, encode the em dash (—) as <code>&#8212;</code>.</p> <p>Do not use references to Windows CP1252 code points even if they appear to work. That is, do not use <code>&#151;</code> for em dash (or any other references to the 128…159 range).</p></li> | All tags and attributes in lowercase. We may decide to switch to | XML in the future, so get in the habit. s/XML/XHTML/ XML doesn't require lower case. It just requires case-sensitivity. I'm not sure that is a good requirement. The mozilla.org HTML content would require programmatic processing anyway if the switch to XHTML was made. OpenOffice.org Writer/Web for one emits upper case tags, and I don't see why documentation authors should bother to change the tags to lower case. | Don't use <meta http-equiv> tags. Composer likes to put in | noise like this: | <meta http-equiv="Content-Type" | content="text/html; charset=iso-8859-1"> That stuff is needed because * It helps when the documentation is browsed from a local disk * Until www.mozilla.org is migrated to Apache, the charset parameter is going to continue to be missing from the real HTTP header. At present I'm not aware of concrete plans on such migration. | Unfortunately, that tag makes 3.0-vintage Navigators load | the document twice and generally lose their minds. Come on. That's an obsolete excuse. | You are encouraged to use our Templates, which have been | designed with this in mind. Are those available outside Zope? | Don't depend on any particular presentation for a tag or class. s/tag/element/ | The style attribute is banned from mozilla.org pages with | two exceptions: float and clear. What's the rationale behind the exceptions? | Pages must look decent in NS4+, MSIE4+, and Mozilla. Try to | avoid exposing bugs in their CSS support; at the very least, | make the page legible. A very useful resource is Eric Meyer's | Master Compatibility Chart. If you must, block a problem | browser from accessing your style sheet�but try to do it | without scripting, ok? For example, @import a style sheet | NS4.x shouldn't see. Suggested replacement: Pages intended for people who aren't yet using Mozilla must be legible in Netscape 4.x. Rationale: "Decent" is ambigous in this context. It makes no sense to accommodate developers who aren't eating their own dogfood by spending time on checking whether the developer documentation pages trigger bugs of obsolete browsers. Also, many (most?) people have no reasonably easy way of checking pages with IE 4. | Add meta description and keywords to help indexing. What's the concrete use case that justifies this requirement? www.mozilla.org is currently using the Google site search. Is there any evidence that including this stuff significantly helps with Google? Rumor has it that Google ignores such metadata. > http://moz.zope.org/contribute/writing/markup I can't access that document. "The proxy server received an invalid response from an upstream server." > The style rules, which have likewise been revamped, are here: > http://fantasai.tripod.com/Mozilla/2003/doc-style/persistent-style.css > http://fantasai.tripod.com/Mozilla/2003/doc-style/persistent-styleC.css I'll have a look at the style sheets later. -- Henri Sivonen [EMAIL PROTECTED] http://www.iki.fi/hsivonen/ Mozilla Web Author FAQ: http://mozilla.org/docs/web-developer/faq.html
