HTML Standards

ACS Documentation : ACS Engineering Standards : HTML

The Big Picture

A typical HTML document in ACS is a static page containing documentation. But, a lot of HTML also shows up in our dynamic pages and in code that we write that generates presentation. As a general rule, we should follow the standards below so that we know they are made up of reasonably well formed HTML. Note that this document is indepedent from, and orthogonal to any style guidelines that might exist at some site where the documentation is installed.

The 80 Column Rule

Make sure that your HTML file will be easily editable in most text editors (i.e. emacs). This means that text should be wrapped at 78 to 80 columns with explicit line feeds or CRLF pairs. Many WSYWIG HTML editors do not do this. Be careful.

General file format

Files should look like this:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">

<head>
<title>HTML Standards</title>
</head>

<body bgcolor=white>

<h2>HTML Standards</h2>

by <a href="mailto:me@arsdigita.com">Author Name</a>

<p>

<hr>

<h3>The Big Picture</h3>

<p>
...
</p>


<p></p>
<hr>
<p></p>
<address><a href="me@arsdigita.com">Author Name</a></address>

Last Modified: $Id$

</body>
</html>

</pre>
</blockquote>

Some things to note:

Try to be good about having a close tag for every open tag. Even though it seems useless for tags like <p>, doing this right will save your butt some day.

Arguably you should indent content between tags to show the block structure of the document. I find that this makes editing annoyingly tedious in Emacs, so I'm pretty bad about this.

Don't use tools like Front Page, Netscape, or Microsoft Word that add a lot of extra HTML nonsense like explicit font tags, gratuitous style sheets or other useless presentation tags that we don't need. Microsoft tools are particularly bad at this. If the tool won't put out a file that you can edit in Emacs, don't use it.

Tag Properties

All tag properties should be correctly delimited strings. For example:

<a href="http://server.somewhere.com/some/path/in/server.html">
This is a URL
</a>

The quotes are important, don't leave them out.

Links

URLs show up a lot in our code and in our static content. Here are rules about how to use them:

Use of Abstract URLs should be limited to URLs that refer to non-static pages. The main reason for this is that it is handy for static pages to be mostly browsable when the user is disconnected from the network or otherwise unable to hit a server. This is especially true for system documentation. Using Abstract URLs in these cases makes it much harder for this to work. A second reason to avoid them for static content is that they require the server to do an extra search of the file system to find the appropriate file to serve. For busy sites with a lot of static pages, this is a major concern.

Use relative links where possible, especially in pages that are all linked together in a single directory within the site.

When linking to the index page of a directory, do not explicitly name the index file (index.tcl, index.adp, index.html, etc.). Instead, use just the directory name, for both relative links (subdir/) and absolute links (/top-level-dir/). If linking to the directory in which the page is located, use the empty string (""), which browsers will resolve correctly.

Tables

Format tables like this:

<table>
<tr>
<th>
heading 1
</th>
...
<th>
heading N
</th>
</tr>
<tr>
<td>
cell 1
</td>
...
<td>
cell N
</td>
</tr>
</table>

This table will look like this:

heading 1 ... heading N

cell 1 ... cell N

heading 1	...	heading N
cell 1	...	cell N

Feel free to add style parameters to suit your taste.

If you want, you can indent the various table tags. It is particularly important that you close all table tags because weird things can happen with malformed tables in various browsers, especially Netscape.

Other General Comments

Frames are almost always a bad idea.
Avoid using style sheets and explicit font control unless you have some really compelling reason to do so. Since much of our static content is documentation and we should care more that it be comfortably readable more than we should care about some notion of cool graphic design. Most browser users have their preference set up the way they like them, we shouldn't override their choices gratuitously.
If in doubt, run an HTML validator. Tidy is a nice tool.

Some other useful hints can be found on the Composing Good HTML page.

Pete Su

Last Modified: html-standards.html,v 1.1 2001/01/21 01:49:07 bquinn Exp