HTML Philosophy and Tutorial

Web Design Philosophy

If you haven't read the introduction to web design philosophy, you should do that first. It covers the general philosophy to be applied to all languages, and you should understand it before reading this document.

HTML Philosophy

Use HTML to define meaning and intent.

The target audience is software. Use HTML only to mark up the natural data so that it can be understood by computer programs. Do nothing to control its eventual appearance or presentation.

Terminology

You are likely already familiar with these terms, but this will serve as a reminder.

data

is the original text of the document being marked up.

metadata

is something that describes the data.

tags

are the <name>text</name> metadata markers that are added to a document to declare the semantics of the enclosed text.

attributes

optionally appear within the opening tag: <tag name1="value" name2="value">. They consist of an attribute name, an equal sign, and a quoted value. Those values are the metadata.

self-closing tags

are tags that are purely metadata and never contain any text data. Also known as void elements, they are generally used to provide data that can't otherwise be represented as text (e.g. an image stored in an external file). Rather than having a closing tag they are written as a single marker with a slash immediately before the final >. E.g. <img src="..." />, rather than <img src="..."></img>.

What Markup Language Does

 <entry>
    <word>...</word>
    <pronunciation>...</pronunciation>
    <derivation>...</derivation>
    <definition>
       ...
       <quotation>
          ...
          <date>...</date>
          <author>...</author>
       </quotation>
       <quotation>
          ...
          <date>...</date>
          <author>...</author>
       </quotation>
    </definition>
    <definition>
       ...
       <quotation>
          ...
          <date>...</date>
          <author>...</author>
       </quotation>
    </definition>
 </entry>
			

A markup language is a language that enables you to mark up existing documents in a way that makes them more understandable to computer programs.

By the 1980s, the gigantic Oxford English Dictionary had become far too large to maintain by hand, but converting it into a computer database seemed like an almost impossible task. Simply converting the printed copies (nearly 23,000 pages) into computer files wasn't enough to be useful; the software needed to be able to separate individual entries, and to know which parts were the word, which the definition, etc. The answer was to use a form of GML to mark up the text, labeling the semantics so that it could be understood by the software. The result of that massive project was something like what is shown here, with the ... representing the original text.

Now any program could access this data, select the relevant entries, and display the results in whatever format was suitable. For instance, by selecting only those entries and definitions that contained quotations dated before 1700, one could produce a printed dictionary that would represent the English language as it appeared 300 years ago.

What Markup Language Doesn't Do

The original printed OED used different fonts and sizes to make the various parts of each entry more obvious to the reader. What is intelligent about the OED conversion process was that they did not attempt to preserve these fonts; instead they preserved the semantics. There is nothing in the markup to indicate what anything should look like, or even what order any of the parts should appear in.

And that is the significant concept you should learn from this. Markup language is intended strictly for communicating with a target audience that is nothing but computer software. That this software will eventually format the data into something that will appear on paper or on computer screens is irrelevant. If we attempt to communicate any information about formatting, we are defeating the purpose of the language and writing for the wrong audience.

That same concept is what you must follow when using other markup languages, in our case HTML.

HTML

The original version of HTML behaved exactly as it should, allowing one to mark paragraphs, lists of items, headings, etc. But a large number of problems, and corresponding bad solutions, soon appeared.

CSS and XHTML Save The Day

By the late 1990s, the whole language was a mess, totally missing its original purpose.

Fortunately, two new languages were introduced to rationalize the situation, XHTML to provide the original purpose of HTML, and CSS to provide the formatting capabilities. CSS will be discussed in a following document.

XHTML requires strict parsing rules. Rather than silently compensating for coding mistakes, browsers that detect syntax errors report them and stop processing the page, thereby almost guaranteeing that the maintainers will use correct syntax. It also means that web crawlers, such as those used by Google to create their index, can make much better sense of what a web page is about.

It's sad to say, but too many people learned to write web pages in the 1990s and still haven't changed their mindset, and since then too many new people have learned by following their bad examples.

Even if you do nothing else suggested in this document, you should always name your files with the .xhtml suffix, so that browsers will quickly point out any inadvertent mistakes you might make.

XHTML

XHTML isn't perfect yet, but it is so much better than what came before. With a little personal discipline, you can follow conventions that eliminate its remaining problems.

Doctype, Head, and Body

 <!DOCTYPE html>
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 ...
 </head>
 <body>
 ...
 </body>
 </html>
		

The data for a web page has two parts, the document type and the actual HTML.

The document type is normally the first line of the file, and exists simply to inform the web browser that the document contains modern HTML, as opposed to older HTML or some completely different language. Though <!DOCTYPE html> looks like an HTML opening tag, it isn't; there must be no matching closing tag, nor self-closing />. Note that the use of upper-case and lower-case is required.

The HTML section is in real HTML format, and contains two parts, the head and the body:

 <head>
   <meta charset="UTF-8" />
   <title>...</title>
   ...
 </head>
				

 <head>
   ...
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <meta name="description" content="..." />
   <meta name="keywords" content="..., ..." />
   <link type="text/css" rel="stylesheet" href="style.css" />
   <style>
   ...
   </style>
 </head>
				

header
   h1
   p
article
   p
   h2 section
      p
      h3 section
         p
	 p
      h3 section
         p
   h2 section
footer
   nav
			

Accessibility and Portability

Making web pages accessible (e.g. useful for visually impaired people) and portable (e.g. useful on different physical devices or with different brands of browser software) used to be difficult and required very complex solutions. But that was only because people went out of their way to accomplish it (e.g. specifying different font sizes under different conditions).

By following the principle of totally ignoring formatting and appearance when writing HTML, nearly everything that is needed is automatically provided by the web browsers themselves. And most of what is left to do can be accomplished by using useless semantic tags and attributes (e.g. the scope="col" attribute on a <th> tag).

Other minor details, such as having links too close together on a non-mouse device, can easily be handled in CSS, a topic in the next document.

From the HTML point of view, the only real concern is with the use of images and other visual objects that are inherently not accessible. In most cases these can be handled by appropriate use of alt attributes. Be sure that these alternative descriptions are meaningful. Don't say mountain, when what the image really means is Photograph of mountain, showing white snow at top, brown and gray cliffs in the middle, and green forest below the tree-line. The three bands have sharp horizontal separations.. Tell exactly what the image is (photograph of mountain), and what details the image is supposed to be illustrating (three distinct layers of terrain).

Not only will this make your page comprehensible to someone that is visually impaired, it will also make it useful for people that don't download the image because of slow or expensive network connections. And (for some people, most importantly), search engines themselves should be considered visually impaired.

Figures and Asides

The main difference between figures and asides is whether you consider them to contain information essential to the document or to have interesting but non-essential content.

A list of names or a photograph of the members of the City Council could be a figure in an article about recent zoning decisions. In the same article, an anecdote about a councillor's being a descendant of the first mayor could be an aside.

The difference becomes important in such situations as when a browser is told to display only the article, omitting non-essential parts like navigation and asides.

Images

Images should almost never appear by themselves, but as part of some containing object.

Visit the
<a href="https://www.w3.org"
    title="Web Standards">
  <img alt=""
    src="https://www.w3.org/favicon.ico" />
WWW Consortium</a>
for specific details.
			

Visit the WWW Consortium for specific details.

Occasionally they are used inline with text, typically to provide a visual enhancement, not to provide essential information. For instance, within an anchor, you might want to display an icon related to the URL. In this case you would give an empty value to the alt="" attribute, since you don't want a broken image symbol to be displayed if the image is somehow unavailable.

More typically you would put images within a table element, a figure, or an aside. Give the image a meaningful alt= attribute, and use the <figcaption> tag to provide a reason for having the image.

For inline images, use CSS to limit the height of the images to the same size as the text, and to allow images to fill the fulll width (or percentage width) of a figure. (This is discussed in the next document.)

Tool Tips

The increasing popularity of touch-screen devices, which lack mouse cursors, has reduced the usefulness of the title="coment" attribute. It is still a good idea to include them though, for cursored devices, for internal documentation, and in the hope that future browsers will provide the equivalent of hover without a mouse cursor.

Be fluent in <abbr title="HyperText Markup Language">HTML</abbr> and <abbr title="Cascading Style Sheets">CSS</abbr>.
			

It is especially useful with the <abbr> tag, allowing the user to see the full meaning of an abbreviation.

Whenever someone positions the cursor over an item that has a title= attribute, the browser displays a tool tip, a small pop-up box containing the associated comment. This provides instant help to the user, whether explaining the meaning of a possibly unfamiliar term, giving a reference for a quotation or fact, or describing the effects of selecting a button.

Some browsers indicate the presence of tool tip popups by means such as a dotted underline or a ? cursor. (For consistency across browsers, you can control this behaviour using CSS.)

Headings

HTML provides six headings, h1 through h6.

The most common mistake people make is to use these simply to produce different font types and sizes. That is style, not markup.

h1 HTML Philosophy and Tutorial
h2     Web Design Philosophy
h2     HTML Philosophy
h2     HTML
h3         Different browsers ...
h3         People wanted more control.
h3         People still thought ...
h2     CSS and XHTML Save The Day
h2     XHTML
...
			

You should always nest the headings, always using sequential numbering. Typically there will be a single h1 heading near the beginning of the page, several h2s dividing it into sections, possibly some h3s subdividing those sections, and so on.

Web crawlers use these headings to determine the outline of your document. HTML verifiers often display all your headers as a table of contents of your document. If what is displayed isn't a reasonable representation of what your document is about, you're not doing it right.

Lists

Some people have difficulty deciding which type of list is appropriate, often choosing the wrong one or resorting to a table instead. Generally though, you shouldn't have trouble deciding which to use. HTML provides three kinds of lists:

ordered lists <ol>

have numbers placed before each item.

They should be used when listing items that have a required order (e.g. steps in a recipe), or when other text needs to refer to specific items.

unnumbered lists <ul>

have bullet marks placed before each item.

They should be used when the order of items is not of importance (e.g. ingredients that can be added in any order).

definition lists <dl>

have specified names placed before each item.

They should be used when the order of items is obvious or irrelevant, and each item has a name naturally associated with it (e.g. this list).

???

Pitfalls

Keeping HTML simple and meaningful is mostly a matter of self discipline. But there are some situations where it is very easy to believe you are thinking in HTML but are actually doing something that should be left to CSS.

???

Summary