World Wide Web Consortium Member Find out more about usContact WinWriters at 1-800-838-8999
Link to WinWriters home pageReceive information about our eventsLink to our discussion and jobs ForumLink to the Online Help Resource Directory
Link to WinWriters home

Using Web Standards to Create HTML Files

By Char James-Tanny, JTF Associates, Inc.

Contents

Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

Introduction     Link to the article Contents

More than writers in most industries, Help authors and technical writers know about standards. We design them for our companies. We ask others to follow the standards we've designed. We implement style guides, formatting guides, standard procedures and techniques, and more.

We create well structured documents that use consecutive heading levels to identify information hierarchies. We format documents using styles and we cringe when we have to edit documents that aren't well structured or well formatted.

We've already learned the importance of structure and formatting. We know that it costs money and time to fix incorrect documents. In this difficult economy, when all companies are looking for solid returns on investments, it is important to do what we can to save both time and money.

I've been working with a client to create HTML documentation generated from Word documents, using Quadralay's WebWorks Publisher WordHelp. My team and I reformatted and restructured 1200 Word documents and built six WordHelp projects.

Unfortunately, the previous consultant had implemented a hierarchy that sometimes used Heading 2 followed by Heading 4 and sometimes Heading 2 followed by Heading 5, instead of a consistent heading structure (for example, Heading 1, Heading 2, and Heading 3). WordHelp relies on the structure of the Word documents to build the table of contents. If the structure of the Word documents is inconsistent, the online table of contents doesn't display correctly. The previous consultant never taught the users how to restyle a paragraph, so we had to verify the formatting of every paragraph in every document. Otherwise, the mappings in WordHelp would cause the content to display in a completely different font or color or size.

It took us 600 hours to complete the six projects. Had the 1200 documents been correctly structured and formatted, it would have taken a tenth of the time (60 hours) to build the six projects.

Standards are important.

In this article, I'll discuss the latest standards from the World Wide Web Consortium (W3C), what you need to know about them to create HTML pages, and what these standards means to us as Help authors.

Why Do Web Standards Matter?     Link to the article Contents

When you use Web standards to create and design your HTML pages, they are future-proof, backward compatible, and cross-browser capable (the appearance may be different, but the content will be displayed reliably). Pages that are designed to Web standards work in new browsers without modification and work with any Internet device, while still allowing users with older browsers to see the content. Using standards doesn't cost more time than working without them (actually, the reverse is usually true). And coding to standards means that your pages are easier to maintain.

In contrast, sites designed for specific browser functionality have to be redesigned each time a new standard is released. For example, when I originally designed my site at helpstuff.com and used rollover tabs, I targeted specific browsers in the JavaScript that I used. When Netscape 6 was released, I had to add new functionality, because my rollover tabs weren't designed to work with one of the latest standards. This was after I had already spent hours getting the tabs to work in Netscape 4. Since I had to rework the site anyway, I changed some of the code to work with specific functionality, not specific browsers. Now that the code works with the latest standards, I don't have to worry about new browsers any longer. As long as browsers support the standards, my pages will be displayed correctly.

According to the W3C, which is responsible for designing and maintaining these standards, HTML documents are supposed to be structured around headings, paragraphs, lists, and other paragraph items. Unfortunately, many times an HTML page is designed to mimic print by using FONT tags to control character formatting, BR tags to control line breaks, and non-breaking spaces to control layout. While pages designed this way will often be displayed correctly, maintenance is harder and changes can use a large part of the budget. For example, if all headings have been manually formatted (using FONT tags) as bold navy sans serif, a change requires manually changing every heading to the new style characteristics. When headings are formatted with a Cascading Style Sheet (CSS) definition and tagged appropriately with <h1>, a change requires a modification to the CSS. Not only is this quicker and easier, but it's also much cheaper.

What Are Web Standards?     Link to the article Contents

The W3C follows a process called the "Recommendation track" to build consensus for a Web technology. The steps in the Recommendation track are:

  • Notes
  • Working Draft
  • Candidate Recommendation
  • Proposed Recommendation
  • W3C Recommendation

A Recommendation is the end result of the process, considered appropriate for widespread deployment by the W3C. In other words, a Recommendation is a Web standard.

You can find the complete list of Recommendations at http://www.w3.org/TR/#Recommendations,External link as well as details on any Recommendation. Start at the list of Recommendations and follow the links. Later Recommendations usually build on earlier ones. You can also see the list of Proposed Recommendations, Candidate Recommendations, Working Drafts, and Notes and learn about the process that the W3C follows when considering a new standard.

While all Recommendations are important, this article focuses on the standards for XHTML and Cascading Style Sheets (CSS).

XHTML Standards

XHTML became the standard in 2000 and several new Recommendations have been released since then. The advantage of XHTML is its portability: valid XHTML files can be viewed on any Internet device. This means that, unlike the days of Windows CE Help, we don't need a special compiler for our information to display on a selected device.

XHTMLTM 1.0 The Extensible HyperText Markup Language (Second Edition, 26 January 2000; revised 1 August 2002)

From the Abstract at http://www.w3.org/TR/xhtml1/,External link XHTML 1.0 is the "reformulation of HTML 4 as an XML 1.0 application, and three DTDs corresponding to the ones defined by HTML 4." And, XHTML 1.0 is "a reformulation of the three HTML 4 document types as applications of XML 1.0 [XML]."External link According to Jeffrey Zeldman (A List Apart), "XHTML is XML that browsers think is HTML."

XHTML introduces the concept of "well-formedness." With HTML 4.0, authors could pretty much do whatever they wanted: uppercase or lowercase tags (or a mixture of both), attributes could be quoted or not, empty elements were allowed, and more. XHTML 1.0 requirements are stricter, requiring lowercase tags, quoted attributes, closed empty elements, and more.

XHTML 1.0 includes three Document Type Definitions (DTD):

  • Strict — You cannot use any presentation elements, such as "align" within the image tag. 
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
          "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

  • Transitional — You may use some presentation elements. Transitional is a bit easier for those already familiar with HTML and CSS, as it allows for some flexibility when creating HTML pages. 
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

  • Frameset — Use with frames. 
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN"
         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">

XHTML 1.0 Transitional is the most commonly used DTD. See Creating Valid HTML/XHTML for more information.

XHTMLTM Basic (19 December 2000)

From the Abstract at http://www.w3.org/TR/xhtml-basic/,External link "The XHTML Basic document type includes the minimal set of modules.... It is designed for Web clients that do not support the full set of XHTML features; for example, Web clients such as mobile phones, PDAs, pagers, and settop boxes. The document type is rich enough for content authoring."

XHTML Basic does not support the style, script, and noscript elements or frames, as these items may not be applicable to small Internet devices.

XHTMLTM 1.1 - Module-based XHTML (31 May 2001)

From the Abstract at http://www.w3.org/TR/xhtml11/,external link "The purpose of this document type is to serve as the basis for future extended XHTML 'family' document types, and to provide a consistent, forward-looking document type cleanly separated from the deprecated, legacy functionality of HTML 4 [HTML4]external link that was brought forward into the XHTML 1.0 [XHTML1]external link document types."

XHTML 1.1 is portable to different client devices, such as PDAs and cell phones, as well as browsers. Many deprecated elements and attributes have been removed from XHTML 1.1, because it relies on style sheets for presentation.

Cascading Style Sheets Standards

Cascading Style Sheets have been a Recommendation since 1996, although browser support has been slow to catch up. (See Working with Various Browsers.) By using CSS, you separate content and presentation, which allows users to control how Web pages appear and also makes updating the presentation much easier. CSS3, currently a Working Draft, separates the various aspects of CSS into separate modules, which should make it easier for browsers and developers to support the standard.

Cascading Style Sheets Level 1 (17 December 1996, revised 11 January 1999)

From the Abstract at http://www.w3.org/TR/REC-CSS1,external link "This document specifies level 1 of the Cascading Style Sheet mechanism (CSS1). CSS1 is a simple style sheet mechanism that allows authors and readers to attach style (e.g., fonts, colors and spacing) to HTML documents. The CSS1 language is human readable and writable, and expresses style in common desktop publishing terminology."

The CSS1 Recommendation included the "cascade" feature and defined how conflicts between various style sheets were resolved.

Cascading Style Sheets Level 2 (12 May 1998)

From the Abstract at http://www.w3.org/TR/REC-CSS2/,external link "This specification defines Cascading Style Sheets, level 2 (CSS2). CSS2 is a style sheet language that allows authors and users to attach style (e.g., fonts, spacing, and aural cues) to structured documents (e.g., HTML documents and XML applications). By separating the presentation style of documents from the content of documents, CSS2 simplifies Web authoring and site maintenance."

CSS2 includes all the functionality of CSS1 and also supports media-specific style sheets, allowing authors to customize the presentation for various devices, paged media, relative and absolute positioning, and more.

Working with Various Browsers     Link to the article Contents

Standards are great, but they aren't equally supported in the various browsers.

Check the table below to see how Cascading Style Sheets are supported in each browser. For more information, see CSS2 Tests,external link which compares various CSS2 properties against:

  • Netscape 4
  • Internet Explorer 4 and 5 (Windows and Mac)
  • Internet Explorer 5.5 and 6 (Windows)
  • Opera 5, 6, and 7
  • Konqueror
  • Mozilla
  • iCab
  • OmniWeb

Konqueror lists its CSS2 support at http://www.konqueror.org/content/khtml_css2.html.external link

So what do you do?

First, decide which browsers you want to support. According to Vincent Flanders in Chapter 4 of Son of Web Pages That Suck, "The correct answer is that your site should look good in all browsers. The second-best correct answer is that you should support the browsers your visitors use."

The hardest part for Help authors to understand is that "look good" doesn't mean "look identical." We very carefully check our HTML output in as many browsers as possible, tweaking to make sure that it looks the same. I've been guilty of furthering this by presentating sessions at WinWriters Annual Conferences that talk about how to accommodate the browser differences. However, instead of spending hours tweaking the code, we can now spend our time creating content.

If a target browser has partial or buggy support for one of the current CSS standards, it doesn't mean that CSS doesn't work at all—it means that some parts of the specification don't work. Even Netscape 4 gets a few things right.

Internet Explorer tends not to be a good test browser, as it doesn't demand compliance—it displays content that won't display in a compliant browser. For example, if you forget the closing table tag, the page appears in Internet Explorer as if the close tag was present. When testing your pages, use a compliant browser, such as Mozilla, Opera, or Netscape 6.

Standard

Browser Support

CSS1

IE4 (partial), 5 (partial and buggy), 5.5 (buggy), 6

N4 (buggy), 6, 7

Opera 4 (partial), 5 (Mac), 6 (Windows), 7 (still in Beta)

Mozilla 1

Mac 4.x (buggy)

Mac IE 5

CSS2

IE 5.5 (weak), 6

N6 (partial, Mac and Windows), 7

Opera 4 (partial), 5 (Mac), 6 (Windows), 7 (still in Beta)

Mozilla 1 (limited)

Mac IE 5 (partial)

  

Check the various CSS bug lists for specific information. These include:

Creating Valid XHTML     Link to the article Contents

If you don't yet know how to create HTML pages that meet one of the older standards (such as HTML 4.0), use one of the many tutorials available on the Web. If you know how to create HTML pages, but haven't yet ventured into XHTML, you need to make sure that your pages use the following:

  • DOCTYPE and Namespace. According to Carrie Bickner in the NYPL online Style Guide,external link "XHTML documents must begin with tags that tell the browser how to interpret them." Select the DTD that you want to use from the list under XHTMLTM 1.0 (if you're moving from HTML to XHTML, start with the Transitional DTD, as it's the closest to HTML).
  • The correct structure. Bickner says, "Think in terms of traditional outlines." This means consecutive heading levels (1, 2, 3, etc.) and paragraphs after headings.
  • Well formed documents, including closing tags or correct form and correctly nested elements. Unlike HTML, XHTML requires closing tags for all elements, including singletons (for example, use <br /> instead of <br>). Actually, HTML has always required correctly nested elements, but it wasn't always enforced (especially in Internet Explorer). Now you must nest and not overlap elements. For example, <strong>bold <em>italic</em></strong>, not <strong>bold <em>italic</strong></em>.
  • Lowercase element and attribute names. When creating HTML pages to the HTML 4.0 standard or earlier, it didn't matter if you used <h1> or <H1>. However, XML is case-sensitive, so XHTML is case-sensitive, which means that <h1> and <H1> are different tags.
  • Quoted attributes. Again, when creating HTML pages to the HTML 4.0 standard or earlier, you could use or omit quotes without problems. For XHTML, however, all attributes must be quoted (for example, width="80").

When you use the correct DOCTYPE, browsers display your pages in "standards" mode, which means that the page is strictly rendered according to the W3C Recommendation. What happens if you use an incomplete or outdated DOCTYPE? Browsers display your pages in "quirks" mode, which means that the browser tries to mimic old browsers. This includes things like not inheriting styles into tables. You want to be sure to use the correct DOCTYPE so that your pages render correctly. For a list of current DOCTYPEs, see Fixing Your Site with the Right DOCTYPE.external link

You can use any tool that creates valid XHTML Transitional (where "valid" is determined by the W3C's HTML Validator) and valid CSS (where "valid" is determined by the W3C's CSS Validator).

For more information, or to get tips on converting many HTML pages to XHTML, visit the NYPL online Style Guide XHTML: Authoring Tips & Tools.external link

Using Cascading Style Sheets

When you are using Web standards, you must use Cascading Style Sheets (CSS), which allow you to attach styles to HTML pages. As the W3C Recommendations continue to mature, external style sheets are preferred over inline and embedded styles.

Part of the reason is that users have complete control over how your pages display. (They have this for WinHelp, too, although very few users—or developers!—know how to modify their system settings to change the appearance.) They can choose to ignore your style sheet and load their own, or they can choose to ignore your colors, font families, and font sizes by modifying their browser settings. This lets users do things like specify larger font sizes or use color schemes that work for them.

You can allow for some of these options by including a JavaScripted Style Switcher on your site. The nice thing about XHTML and the separation of presentation and content means that you can change the look of a page by doing nothing more than assigning a different style sheet. You can see this at Eric Meyer's personal site.external link

Hiding the CSS from Older Browsers

Using standards means that you don't have to design your site and then figure out how to get it to work in all browsers. By getting your design to work with standards, you know that the content will always display, even on older browsers.

One trick is to hide your "complicated" CSS from browsers that can't use it by using @import. This lets you pass a CSS so that older browsers can display the content, although not your design. @import is ignored by N4, but not by Internet Explorer 4+, Opera, Netscape 6+, Mozilla, or Amaya.

@import should appear before any other style declarations. See ImportHackexternal link for the instructions on how to create an imported CSS if you need to hide your CSS from Netscape 4.

Another method is to link to the second stylesheet after linking to the first, but to specify a media type (all, aural, braille, embossed, handheld, print, projection, screen, tty, or tv). Netscape 4 ignores any media type except "screen." Internet Explorer 4 uses "all," "screen," and "print." For example:

<link rel="stylesheet" href="helpstuff.css"
      type="text/css" />
<link rel="stylesheet" href="helpstuff-up.css"
      type="text/css" media="all" />

This delivers helpstuff.css to all browsers and then delivers helpstuff-up.css to all version 5+ browsers and version 4+ of Internet Explorer.

What About JavaScript?

JavaScript sniffers have been available for years. In fact, up until October 2001, Netscape's site included the Ultimate Sniffer Script, which tested for all known browsers and versions.

However, it is better to sniff for functionality, as sniffing for specific browsers can lead to problems. One recent example is the newly redesigned HotBot site, which recognizes Netscape 7 as a browser that supports Web standards, but not Mozilla (which Netscape is based on).

Sniffing for functionality means that you check for a specific feature in the DOM. For example, the following code tests for specific browser functionality:

if (document.getElementById) {
// tests for all other compliant browsers }

else if (document.all && document.getElementById) {
// tests for IE 5, 5.5, 6 }

else if (document.all && !document.getElementById) {
// tests for versions earlier than IE5 }

else if (document.layers) {>
// tests for Netscape 4 }

However, you don't have to sniff for a browser if you only want to see if a specific piece of functionality exists. For example, rollovers work with all browsers that support document.images. Therefore, you could use just the following code:

if (document.images) { }

Of course, there is still one more issue. Internet Explorer 5.5 and iCab test true for getElementById, but they don't support it. You may have to add a specific browser sniffer after testing for functionality if your Web statistics show that you have users visiting your site with Internet Explorer 5.5.

Learning About the "Hacks"

With every new browser version, we deal with more information—and more workarounds. Various hacks have been documented to work around some of the issues.

The most famous (or at least the one discussed most often) is the Box Model Hack, which is necessary for all versions of Internet Explorer previous to version 6. Basically, the W3C states that the width of a box includes its contents, padding, borders, and margins. Internet Explorer versions before 6 (and Internet Explorer 6 in "quirks" mode) use the specified width of the box to determine the width, and then puts the other values inside the box.

See BoxModelHackexternal link for more information and links to several fixes.

Creating "Fancy" Sites

Many developers, when faced with layouts that use standards, think that they will be forever faced with boring, dull sites. Not true! Sites are getting more creative as developers learn how to work with the standards and understand how the different browsers interpret relative and absolute positioning.

One of the best places to see what people are doing with CSS and standards is the CSS-Discuss list.external link You'll be able to see cutting-edge sites before they go public and learn an immense amount about CSS and standards. You don't have to post any answers, as lurkers are welcome. If you do decide to post, make sure you read the rules first!

Since I started paying attention to which sites are and aren't developed according to standards, one thing I have learned is that appeal is relative. You may not like sites that I do, but sometimes I'm impressed by the technique. Sites that I like are:

Validating Your Files

Some tools, such as HomeSite and Dreamweaver MX, include built-in validators that let you check your HTML (and CSS) during development. You can also use:

Viewing the Results

You could install every browser to see what your results look like (although you can't install more than one copy of Internet Explorer on your system at one time). Or you could use one of the following tools:

What About Accessibility?     Link to the article Contents

Accessibility is very important today. Section 508 compliance and the American Disabilities Act require that sites are available to all users, not just those who can see and type.

Some quick tips and tricks:

  • Make sure that your documents are structured correctly. Screen readers can interpret headings and read the outline to the user.
  • Make sure that all images have alt attributes, unless they aren't necessary, in which case you should add a blank one. For example, in HTML-based Help (with the navigation tabs on the side), some tools add a graphical bar that fills in the left pane. This bar doesn't need any alt text, as screen readers don't need to interpret it.
  • Use alt attributes that make sense. For example, if your page includes a company logo, link it to your home page and add the appropriate alt attribute ("link to home page").
  • Use <strong> and <em>, which are functional tags, instead of <b> and <i>, which are formatting tags. When aural media types are implemented, the voice will interpret <strong>, but how should it implement <b>?
  • Make sure that a mouse is not required to use the page.
  • If using JavaScript, use onfocus and onblur instead of onmouseover.
  • Don't use tables for layout unless they make sense when linearized (that is, read from left to right, row by row). For data tables, use row and column headers.
  • Use meaningful text for hyperlinks. "Click me" doesn't tell the user where they will go if they click the link.
  • Don't open new windows or popups without informing the user.

For more information on accessibility, see User Agent Accessibility Guidelines 1.0, 17 December 2002 (http://www.w3.org/TR/UAAG10/external link).

Disabling Different Options

Want to disable all colors? See what a page looks like without style sheets, which lets you view the structure? Quickly verify that all your images have alt attributes? Visit DiamondTM Demo Toolsexternal link to download and install bookmarklets that you can trigger with a click on any site.

What Do Standards Mean to Help Authors?     Link to the article Contents

Now that you know all about standards, what do they mean? When you learn how to code to the latest Web standards, you can:

  • Design and develop pages that work anywhere—within browsers, PDAs, cell phones, even refrigerators!
  • Fix mistakes caused by your authoring tool.
  • Make your pages more accessible.
  • Save your company money.

If you have learned any bad habits over the years, now is the time to unlearn them. You no longer have to remember how to get something to display correctly in Netscape 4 or worry about using browser-specific functionality.

HAT Comparison

As a result of a collaborative effort by a group of Help industry consultants, you can compare the HTML, CSS, and CHM files produced by leading authoring tools. Visit http://www.knopf.com/resources/hatcomp/index.htmlexternal link to see the metrics and the results of the tests.

At this time, only Macromedia's Dreamweaver MX produces valid HTML/XHTML. Preliminary tests on AuthorIT Version 4 show that it also produces valid XHTML. (AuthorIT Version 4 is scheduled to be released in January 2003.) AuthorIT, Dreamweaver MX, WebWorks Publisher, and WebWorks Publisher WordHelp all produce valid CSS files.

If you want to be able to produce valid files that can be viewed anywhere, these tools will make your job easier.

Links to More Information     Link to the article Contents

In addition to the links used throughout this article, you might also want to check:

Copyright 2003, Char James-Tanny

Char James-Tanny has more than 20 years experience as a technical writer and is well known in the Help community for her knowledge of online Help tools and concepts. The author of two books, she speaks frequently at conferences around the world on Help topics, cross-browser issues, and tool-specific functionality. Char is a senior member of STC's Boston Chapter, a member of MACCAWS (Making a Commercial Case for Adopting Web Standards), and a 2003 Microsoft WinHelp MVP.

up

Copyright © WinWriters. All Rights Reserved.
Joe Welinske: jw@winwriters.com
Last modified on