../ -- html.html

HTML Style Guides

updated 2007-02-19.

"Everything I know about HTML and CGI" . .

Contents:

Bramble's Graphically Challenged Award Valid HTML 4.01!

See also

[FIXME: since Quality Tips for Webmasters http://www.w3.org/2001/06tips/ is asking people to submit tips, perhaps I should move my tips from here to there ... ]

[FIXME: consider moving most of this information from here to http://massmind.org/techref/language/html/ ]

how I set up my web pages

My goal is to make stuff on my web site maximally visible. (If this isn't your goal, why bother to put anything up ?)

My major goals for this site are

I wanted to

To do this, I

[um, actually, I have a few other directories, but I *intend* to move everything to these directories]

Since all my pages (except "index.html") are in my "html/" subdirectory, it's easy for most browsers to get a exhaustive list of *all* my documents by viewing http://www.rdrop.com/~cary/html/ . (And a exhaustive list of all my images by looking in my "image/" directory).

With a book, it's obvious how large it is and how much left there is to view. With a web page, I'm often left wondering, "OK, I've seen 3 interesting pages. Is that it ? Is there just one more page ? Or does this site go on and on for a few thousand more pages ?"

I know I find it frustrating when I'm wandering around some interesting site, getting that deja-vu feeling from seeing the same documents over and over, wondering if I missed some fascinating page somewhere. I try to mention every sub-folder in index.html, letting users know they exist and letting them get there with a simple click rather than manually editing a URL.

While I really like the "previous", "up", "next" concepts recommended in the Style Guide for Online Hypertext and will put them on my pages Real Soon Now, I'm not exactly sure what to do on the last page. I could

( Joshua Kaufman http://unraveled.com/joshua/ has some rants on good and bad "prev" and "next" links )

I'm thinking that, since it's that annoying "index.html" file that is getting in the way of maximum visibility, that I should eliminate it entirely -- or perhaps segregate it as "index/index.html".

For stuff specific to my own site, I start at the root URL http://rdrop.com/ and select "Documentation" | "Authoring web pages on Agora".

Everything I know about HTML (including advice on how to write "good" HTML) comes from these sources:

tutorials

Tutorials and information on the HTML standard (You may not need this if you use a WYSIWYG web page editor like "GNN Press" or "Microsoft Front Page Express", or "export HTML" from Microsoft Word ), but you definitely need to know this if you're going to look at the raw code in a text editor:

color

The default background on many popular web browsers is a ugly grey. There are 2 ways to fix this:

  1. Let your reader set the default background to the reader's own favorite colors.
  2. As the author, set *all* the page colors with something like 
    <html>
...
<STYLE type="text/css">
	BODY { background: black; color: white}
	A:link { color: yellow } <!-- unvisited -->
	A:visited { color: fuchsia }
	A:active { color: white }
</STYLE>
</head>
    (setting *only* the background color is a bad idea according to http://www.w3.org/TR/REC-html40/types.html#h-6.5.1 ). You must do this if you set a background image.

I recommend option 1 for all but the most ultra-graphics-intensive "eye candy" pages. Some people like black on yellow, other like bright green on black. I personally prefer black text on a white background. Wouldn't you rather read text on your own favorite background and foreground colors ? I still don't understand why some authors believe that every reader has exactly the same favorite colors. Some people *like* lots and lots of tiny little letters filling the screen. Other people *like* using very large fonts. Why not give people what they want ?

Every time I move to a new machine, I set up my favorite colors.

In FireFox, I choose

[T]ools | [O]ptions... | Content | [C]olors...

then set the colors, then

OK

.

In Microsoft IE 4.0, I choose

[V]iew | Internet [O]ptions... | General | C[o]lors

then set the colors, then

OK | OK

Why write a FAQ ?

Q: Why would anyone put time and effort into a FAQ, then give it away for free ? Or put anything else on the web, for that matter ?

Abigail says it better than DAV's original attempt an an explanation:

reference

Exhaustive references to the HTML standard. These are useful as a reference after you've read one of the above tutorials. All the picky little details. ( "character entity references" si_metric_faq.html#iso8859 , how to display greek and other symbols ...) These generally have pointers to validation tools and other related links.

HTML validation tools

I need to occasionally check my web site for problems. These tools make it easy to find the most common problems with my web page:

You can skip this section if you never make mistakes.

design advice

DAV: I encourage you to take all the useful information you know and stick it on the web first, before you even *think* about making it look "pretty".

Don't get so caught up in making it look pretty that you forget why you make web pages .

Then make it easy for people to comment on your page by putting your email address on that page (if you're worried about spam, put your email address in a .png picture so it can only be read by actual humans), and by properly linking your page to backlinks #backlinks , and perhaps a guest log, a relevant wiki, and/or a feedback form feedback.html .

Also make it easy for yourself or future maintainers to remember information about your page: Embed metadata #metadata into the page (perhaps in comments).

Once you put your own information up, you should provide links to other related information -- such as people with the same name as your own name #same_name

Only after that information is online should you even think about the following design advice.

It seems that most sites have these pages:

The following links have some really good ideas (design principles)(style)(advice): for "giving your readers a pleasant viewing experience".

see also computer_graphics_tools.html#web for tools to help you make images, icons, buttons, etc. suitable for the Web.

let people use their own preferences

Let people use their favorite browser.

Let people use whatever width window they like.

"liquid design", "flowed"

Rather than force things to be a specific size and arrangement, some people prefer it when things automatically reflow to fit their screen.

General User Interface tips and traps

[FIXME: don't I have more stuff scattered elsewhere to put here ?]

Here I list user-interface ideas specific to web pages.

See also user_interface.html has general user-interface tips for all software (including web browsing).

every document has metadata

Every document has metadata associated with it. I suppose you could just memorize it -- but then, I suppose you could just memorize the contents of the entire file. Given that you're going to write it down somewhere, it's generally a very good idea (especially with program source code) to embed this metadata into the document itself, making a "self-describing file".

book.html#citation

David Cary plans to put *most* of these items of metadata into every document he creates.

``The system can learn a lot about each document just by keeping its eyes and ears open. If the associative retrieval system remembered some of this information, much of the setup burden on the user would be made unnecessary. The program could, for example, easily remember such things as

''

-- p.106 _About Face_ (1995) book by Alan Cooper

"A full understanding of a program ... code ... [and] numerous idems of metadata describing the context in which a program was created and is used. Unlike comments, which usually describe a piece of a program, these metadata refer to the entire program. A partial list of program metadata:

Related to but distinct from the metadata are longer texts that describe the program, such as an abstract, statement of purpose, and history." -- p. 121, _Human Factors and Typography for More Readable Programs_ (1990) by Baecker and Marcus.

For documents that list addresses, each individual address should be dated as to when it was last confirmed. -- DAV

[FIXME: add information about file format header considerations computer_graphics_tools.html#file_formats here -- or link to discussion elsewhere] start compressed file with name, date, compression program, etc.

More about metadata:

backlinks

backlinks are a nifty tool that you might consider adding to your web pages.

Using "view source", you can copy and paste these "forms" into your own pages.

DOCTYPEs

The tip "Don't forget to add a doctype" http://www.w3.org/2001/06tips/Doctype points to

All the following are listed on the 2nd reference ...

Currently I use something like 

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
	"http://www.w3.org/TR/html4/strict.dtd"
>

I'm thinking about switching to 

<!DOCTYPE html PUBLIC
    "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN"
    "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg.dtd">
to give me XHTML + MathML + SVG.

But it's so annoying to have to add all those </p> paragraph-end tags that http://www.w3.org/TR/2000/REC-xhtml1-20000126/ says is required under XML.

CSS: cascading style sheets

CSS and printing to paper

other CSS

[FIXME: ]

About CGI

Using CGI programs that have already been set up

"forms" are sections of HTML files that let users send information back to the server.

A "CGI" script accepts that information and does something with it.

There are already many public machines with CGI scripts you can use, just by putting the appropriate form in your HTML files. ("remotely hosted CGI")

Please check with your own ISP and see what other local CGI scripts you have available to you. Nearly all of them have a CGI script you can use for feedback forms, usually called something like "mailform" or "mailto". ("mailto.pl" is a Perl script written and freely distributed by Doug Stevenson http://www-bprc.mps.ohio-state.edu/mailto/mailto_info.html ). On my system, documentation is at http://rdrop.com/tools/www/mailform/

More on writing your own forms:

Writing and setting up your own CGI scripts

Perhaps these CGI scripts don't do exactly what you want. Then you might be able to write your own CGI script to handle the information returned by forms. This section talks about writing server-side programming. Most ISPs do not allow you to write server-side programs -- so this section will be utterly useless to most people.

see

I far prefer <form method=GET action="..."> over the <form method=POST action="..."> as a form submission method http://www.w3.org/TR/REC-html40/interact/forms.html#submit-format , because it's so much easier to debug. Also, GET allows you to easily do clever things like make some links that have common selections pre-filled.

( "The use of POST rather than GET is a ... obstacle ... If you're starting from scratch and want to use SOAP, make sure your SOAP toolkit supports the HTTP GET mode of access." -- The Beauty of REST by Jon Udell March 17, 2004 http://www.xml.com/pub/a/2004/03/17/udell.html )

To understand how CGI works, it helps to know a little about the standard HTTP protocol. Normally, to fetch a standard HTML page (for example, http://www2.okstate.edu/ ) your local web browser opens a connection with the remote server on port 80. This indistinguishable (at the server end) from you typing 

  telnet www2.okstate.edu 80

from your command prompt. Then the browser requests the specific page (in this case, "/") exactly like you typing 

  GET / HTTP/1.0

(note that you *must* type 2 return characters, "\n\n" after the GET command) and then your web browser waits for the response. By now, if you've been following along, the remote server has replied with something like 

HTTP/1.0 200 OK
MIME-Version: 1.0
Server: WebSTAR/2.1 ID/32004
Message-ID: <b1190587.43075@www2.okstate.edu>
Date: Sun, 01 Mar 1998 20:05:53 GMT
Last-Modified: Wed, 11 Dec 1996 22:10:34 GMT
Content-type: text/html
Content-length: 3375

<P><B><FONT SIZE="+1">

[rest of file snipped to save space] .

Note the blank line ( 2 return characters, "\n\n") between the end of the "headers" the server sent you, and the start of the actual text in the file (the first character in this file is "<").

Then the remote server breaks the connection. (With HTTP/1.1, the connection remains open, so you can request and receive multiple files over the same connection).

When you write your own CGI script, it's often a good idea to run it from the command prompt to make sure it is printing the right things to STDOUT -- minimally, it needs to duplicate the "Content-type" line and the 2 returns after it; my code looks something like gather.cpp.

If your CGI returns a image file, the sequence looks more like this:

You, the browser, do 

  telnet thomppj.student.okstate.edu 80

and you get the response 

  Trying...
  Connected to thomppj.student.okstate.edu.
  Escape character is '^]'.

Then you type 

  GET /~thomppj/images/plant.gif HTTP/1.0

(note that you *must* type 2 return characters, "\n\n" after the GET command), and the web server responds 

HTTP/1.1 200 OK
Date: Sat, 29 Nov 1997 05:07:23 GMT
Server: Apache/1.3b2 Debian/GNU
Last-Modified: Wed, 26 Nov 1997 20:22:30 GMT
ETag: "5768-6a12-347c8506"
Content-Length: 27154
Accept-Ranges: bytes
Connection: close
Content-Type: image/gif

GIF89a.....}

[rest of file snipped to save space] .

Note the blank line ( 2 return characters, "\n\n") between the end of the "headers" the server sent you, and the start of the actual text in the file (the first character in the file is "G").

More about CGI:

DAV: I think the "proper" method of decoding is: 1. Break apart into items (each attribute ... [FIXME] How the characters will be escaped when received by the CGI program: http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13.4

Here are some CGI programs that you might want on your server:

ampersands, semicolons, and CGI scripts

A common error in CGI scrips and links that refer to them:

same name

Think you are unique ? Think again -- do a web seach on your name. Click on "people finder" http://webcrawler.com/ [FIXME:] and type in your name -- I think you'll be surprised at how many of you there are.

I think it is a good idea to provide links to other people with the same name -- I am really impressed with these pages:

Here is my attempt to follow my own advice: david_cary.html .

misc

Once you have some content up, you might think about ways to let someone comment on your work. Of course you *will* put your email address at the bottom of every page, so people can directly respond to you with ideas for improvement and answers to the questions you raise. You can also create a feedback form which is easier for some people to use.

Even cooler than the feedback form is a "guest book", a page that automatically takes comments and puts them on your web site. This is done via "CGI", but if you have one of those annoying sysadmins who don't have a guestbook CGI already set up and who refuse to allow you to set one up, you can still use

www subdomain

The "www" in a URL:

[FIXME: todo: consider adding this "no-www" icon to http://david.carybros.com/ ... i.e., index.html]

unsorted

GNN press makes shareware WYSIWYG HTML editor for Mac, PC, Unix platforms. HTML put "I have, I want" into my Web page; perhaps even into my .signature. Date: Tue, 11 Jun 1996 00:00:08 -0400 (EDT) From: transhuman at umich.edu Subject: >H Digest ... From: "Stephen de Vries" <PHEN at wwg3.uovs.ac.za> Subject: >H 3D Text. Transhuman Mailing List .... Stephen de Vries < Information state > I have : Memory techniques, beginner Delphi, C++, evolution, memes. I want : Practical Chinese, evolution, artificial life.

consider making links to "I wish I had time to create a page on this topic -- would you like to help ?" pages.

"No dead pages"

The Instant Home Page site http://banjo.Cise.nsf.gov/ihp/ihp.html lets the casual user type in the info needed to create a home page ... and the completed form is then saved to your computer.

Tulsa Computer Society: Internet SIG. http://tcs.org/internet.htm Lots of web site tutorials and development links !

Free demo version of Dreamweaver http://www.macromedia.com/software/dreamweaver/productinfo/roundtrip/ OSU College of Arts & Sciences' Web Team. http://wrigley.okstate.edu/

Html Writers Guild http://www.hwg.org/ has help lists for different skill levels.

http://www.creativegood.com/help/ ???

Usable Web: Guide to Web usability resources http://usableweb.com/ human factors, user interface issues, and usable design specific to the World Wide Web.

"ONLY FREEWARE" http://www.cias.net/sawicki/ Includes a long list of HTML tools -- HTML editors, link checkers, books on Java, Java development tools, etc.

http://www.coolnerds.com/

Why server side processing is evil http://www.mired.org/home/mwm/no-ssi.html /* was http://www.phone.net/home/mwm/no-ssi.html */

useit.com: Jakob Nielsen http://www.useit.com/ has good information including "The Alertbox: Current Issues in Web Usability", "the Death of File Systems", "The Anti-Mac Interface", "how people read on the Web". In particular, http://www.useit.com/alertbox/20000416.html makes the interesting statement that

The extra choice requires extra thinking, and the time saved by using an optimal interaction technique is often smaller than the time wasted on having to think instead of just moving ahead with a single interaction technique that is always used. It takes at least one second and often two seconds to decide between two possible interaction techniques which is why it is usually better not to offer users a choice.

possibly related humor: "Care and Feeding of Web Pages" http://homes.jcu.edu.au/~imla/web.html "How to Report Software Bugs (Programmer's version)" http://homes.jcu.edu.au/~imla/drivelbug.html "Please Don't Feed the Engineers" http://homes.jcu.edu.au/~imla/eng.html /* was http://www.jcu.edu.au/~imla/web.html , http://www.jcu.edu.au/~imla/drivelbug.html , http://www.jcu.edu.au/~imla/eng.html */.

http://www.aesthetic-images.com/ebuie/ "Software Usability" "photography"

The HTML Terrorist's Handbook : Composing Evil HTML http://www.zikzak.net/~acb/hacks/htmlth.html being a Guide on the usage of HTML as an offensive weapon. [FIXME: Has this gone offline ?]

The HTML Hell Page http://earthspace.net/~esr/html-hell.html

Fred Langa's HotSpots and BrowserTune, "browser test and tuneup site". http://www.winmag.com/flanga/ mirror http://www.browsertune.com/flanga/

[html.html] Useful WWW sites regarding hypertext, hypermedia, and world wide web. http://www.humanities.mcmaster.ca/hypertext.places.htm includes: "What is hypertext and hypermedia ?" "Hyperfiction" "Bartlett's Quotations" " Strunk's Elements of Style " "Creating High Impact Documents: A guide to visually sophisticated documents from Netscape." [html.html] Guides to Writing HTML http://union.ncsa.uiuc.edu:80/HyperNews/get/www/html/guides.html Pointers to lots of guides on HTML.

A Style Guide for online hypertext http://www.w3.org/Provider/Style/Overview.html has very persuasive arguments for the "Why ?" button.

The proper way credit graphics you use. http://www.ttlhost.com/tananda/setoftheweek.html The proper way to add graphics to your web pages. http://www.widowsweb.com/widows/plea.html

A Webmasters Smorgasbord of Free Resources http://smorgasbord.freeservers.com/

tidy.c - HTML parser and pretty printer http://www.w3.org/People/Raggett/tidy/ Actually *fixes* some of the most common errors, and tells you about errors it finds that it doesn't know how to fix. (free source code from this web page, as well as binary executables for a variety of platforms). Looks pretty useful, for both

. (other source code here for related parsing tools). [FIXME: don't I have other ``pretty printer'' info I could collect in one section ?] [FIXME: do I have more pretty printer links ? idea_space.html#translation ]

WWW and HTML Documentation http://oneworld.wa.com/htmldev/devpage/dev-page.html yet another tutorial / reference page. long list of links to HTML converters and HTML editors.

HTMLGoodies.com http://www.mcp.com/publishers/que/authors/joe_burns/ and http://www.htmlgoodies.com/ ???

Why web usage statistics are (worse than) meaningless http://www.cranfield.ac.uk/docs/stats/

Har's Quick-n-Dirty JavaScript Center http://sklarnet.com/js/jsc.htm "real-world JavaScript ideas and examples with the emphasis on useful and functional instead of cute-but-ultimately-useless."

web design Tips and Tricks http://sklarnet.com/LN/webtips.htm

Jeffrey M. Glover http://jeffglover.com/ wrote "Top Ten Ways To Tell If You Have A Sucky Home Page" http://jeffglover.com/sucky.html "Don't have a hissy-fit if something from your web site is on the list. I encourage you to create your web site however you want, regardless of what some doofus says is "sucky" or "a don't"!"

I used to subscribe to W3C World Wide Web Mailing Lists http://www.w3.org/Mail/Lists.html David Cary subscribed to the "www-html" www-html@w3.org To subscribe, please email www-html-request@w3.org with subscribe as the subject.
http://search.w3.org/Public is a dedicated search engine for the w3.org mailing lists.

Vijay Mukhi's technology cornucopia http://www.vijaymukhi.com/ lots of tutorials and information and source code: Java, socket programming, ActiveX, JavaScript, Netscape Plug-ins, TClets (TCL/TK programs which can be used on the internet via Sun's Netscape plug-in) "I want to spread this program globally, so that the whole world can marvel at my genius."

tools to help optimize a graphic so it downloads very fast from your web page yet still looks reasonably good.

The Web Standards Project: Fighting for Standards in our Browsers http://webstandards.org/

ECMAScript Language Specification http://www.el-mundo.es/internet/ecmascript.html

Standard ECMA-262 ECMAScript Language Specification http://www.ecma.ch/stand/ecma-262.htm

ECMA: Standardizing Information and Communication Systems http://www.ecma.ch/

AOLpress http://www.aolpress.com/ seems like a pretty nice WYSIWYG HTML editor (I really like the "check links" feature). Macintosh and Windows versions available. Note that you do *not* need a AOL subscription to get this free software.

http://www.cnet.com/Content/Reviews/Compare/Browsers4/ss01a.html latest web browser comparisons (Microsoft Internet Explorer v. Netscape Communicator)

DAV: I often use the term "URI" ( http://www.w3.org/TR/REC-html40/types.html#type-uri ). "URI" is not a typo.

WTS - Web Tree Scanner is a program to visualize the tree of a WWW server and check the links. http://www.fsai.fh-trier.de/~schmitzj/Xclasses/programs.php?prg=wts published under the GPL. /* was http://www.fsai.fh-trier.de/~schmitzj/Xclasses/programs.html */

Open Group http://www.opengroup.org/ ???

Web Page Evaluators http://www.cgu.edu/degrade/evaluators.html

http://cgi-lib.standford.edu/cgi-lib/ "is the home page for the cgi-lib.pl library which is ... the de facto standard library for creating cgi scripts in the Perl language. It also contains good descriptive information, examples"

"The Language of the Internet" article By Eddie Rabinovitch http://www.comsoc.org/ci/public/1998/feb/internet_column.html /* was http://pubs.comsoc.org/ci1/public/1998/feb/internet_column.html */

"Improving Your Web Site: Tools, Ideas, and Gizmos" article by Eddie Rabinovitch http://pubs.comsoc.org/ci1/public/1999/aug/

standard footer: why ?
so I won't forget the following.
full URI of the file: why ?
so if people print it out, they can go back to the online version to check for updates.
date file last modified: why ?
??
date file started: why ?
because I might want to know when I started it, and if I don't write it down now (and I might as well put it *in* the file, it's metadata), I won't remember.
link pointing to index: why ?
so if people get to this page "sideways" through search engines etc., they can go "up" to my index ("no dead-end pages").
direct email address of maintainer (visible in the browser): why ?
so people who have been given a paper printout of this page can directly respond via email, without the hassle of hunting down the email address of the maintainer.
original author, current maintainer: why ?
to give credit. I know I do better work when I'm get a little recognition from it.

What is the point of the <address></address> tag ? Do I need one ?

Standard footer for all pages DAV writes:

[FIXME: consider adding a Bobby link http://bobby.cast.org/bobby/bobbyServlet?URL=http%3A%2F%2Frdrop.com%2F%7Ecary%2Fhtml%2Fhtml.html&output=Submit&gl=wcag1-aaa to the footer ?]

[FIXME: Does this look like a good thing to put in the footer of every page ?

Google
WWW rdrop.com

]

This page started 1998-01-15 (but some information much older, going back to 1996 Nov 12) by David Cary and has backlinks

known by AltaVista

known by Yahoo!

known by infoseek . . .

Send comments, suggestions, errors ,

errors , bug reports to

David Cary feedback.html
d.cary+72@ieee.org.

Valid HTML 4.01 Strict

Alas, CritSuit is offline. Is there any replacement for it?

Return to index // end http://david.carybros.com/html/html.html /* was http://rdrop.com/~cary/html/html.html */