This document is intended for anyone who may be interested in any of the techniques used on this web site, and who would like to use them in their own pages. If you would like more information, please e-mail the author at awilliams@itim-ts.com
Topics covered include:
Many of the DP4 Manual Pages were originally converted to HTML from Windows Help files. This was originally done using RoboHelp HTML Help edition, available from www.ehelp.com. However, they are currently maintained using Arachnophila version 4.0, available from www.arachnoid.com, which is free. The pages are built into downloadable manuals in Microsoft CHM format, using HTMLHelp Workshop, which is available as a free download from the Microsoft web site. This program allows you to visually edit table of contents and index files. However, it is rather buggy, and better programs are available for this purpose, for example FAR, which is available from www.helpware.net. (FAR also has many other uses, though in fact I do not use it at the moment). You need the HTMLHelp workshop to get the HTMLHelp compiler, even if you do not use the program to develop documentation, if you want to generate CHM files.
The help pages are available online using either the ActiveX HTMLHelp control, which only works in Internet Explorer, or using a Javascript Table of Contents. The former has an index facility, but its table of contents does not work well. I only provide it because it requires little or no work to maintain.
The Javascript menu is built using an adapted version of Morten's Tree Menu, available from www.treemenu.com. If you want to use a tree menu, I recommend visiting this site, as it contains extensive information on how to configure the menu. Utilities are also available for generating the table of contents. However, I do not know about these as I use my own utility, convhhc, to generate the table of contents from .hhc files.
My modifications to the tree menu are as follows:
These are the only changes necessary to get my .js files working with the tree menu. Other changes were because of specific requirements of the DP4 web site.
MTMakeLink() has been adapted for the search facility. Morten's version of this needs changes for the Explorer style menu I use.
You can download my version of mtmcode.js. The frameset for the manual pages uses code.html which I have renamed with .txt extension to allow you to inspect/download the source without opening the menu. The page displayed when the documentation frameset is first loaded sets the name of the table of contents to load. If you only have one table of contents to load then you can simplify code.html by just referring to the appropriate js file, rather than dynamically changing the name of the script. The Xlib documentation recently added to this size uses Xlibcode.html instead. The only difference is that most DP4 links are removed.
convhhc is a utility that parses .hhc files and can emit various transformations of them. One of its most important features is that it recognises nested hhc files and can emit a merged version of the files. This allows different variants of the same table of contents to be maintained. For example the CHM tables of contents for most DP4 manuals include a "Related Documents" section, and some CHM manuals contain glossaries, or long lists of error messages, which would add considerably to the time needed to load the online table of contents, and have therefore been omitted. The CHM files often have two table of contents files built into them: one displayed when the file is opened in its own right; the other, missing "Related Documents", when it is displayed merged with another help file. This is done to stop the table of contents becoming recursive, (something that can crash the help viewer).
It should be noted that HTMLHelp workshop does not behave well with nested hhc files - in order to get the correct level of indentation at run time the file has to be formatted in a way that causes HTML workshop to malfunction, and corrupt the contents file. Fortunately, there is not usually much need to edit this files once they are created - only the component hhc files are usually changed. FAR's table of contents editor behaves correctly with such files.
convhhc outputs the following transformations of the file filename.hhc:
You can download convhhc.exe or convhhc.c. They are completely unwarranted. The make file I use to build all the DP4 CHM files and the Javascript contents is also available, which shows the various command tails to select the various types of output.
The stylesheets used on the DP4 web site are intended to make pages work well without the need for extensive mark-up, at a wide variety of screen resolutions. In addition all sizes are specified in relative units, so that the pages behave well if the user selects a different font size in the printer. An entirely different stylesheet is used if a page is printed, intended to give a book-like appearance. To see what can be achieved with stylesheets visit the CSS Zen Garden. I have experimented with allowing the stylesheet to be changed on the DP4 web site, but this is not yet ready for release.
There are a few moderately unusual things about the style-sheets, mostly designed to exploit special features of Internet Explorer:
This is floating text, which can be used to put part of a page in a separate area. I prefer it to using tables because surrounding text can flow round it. It uses the xpanel class in my stylesheet.
Pages other than DP4 manual pages use site.css as a stylesheet.
Manual pages uses dp4man.css.
The behavior for the headings is 3dheads.htc.
All pages,apart from framesets, on the DP4 web site now start with the following !DOCTYPE declaration:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
This was originally done to allow all the pages to be validated. However it had an unexpected (to me) side effect: the font size of all text on the site suddenly became smaller when viewed with Internet Explorer 6! The font sizes are chosen to render well at the default resolution of most web browsers. Unfortunately Internet Explorer often uses a much larger default size than other web browsers, and as a result most people would want to use the "Smaller" font size to view the DP4 web site. I felt this was better than rendering the page much too small for users of other browsers. Microsoft have realised the error of their ways, and have changed their default font sizes, however the change only comes into effect for pages that use "Standards Compliant Mode". It turns out that the above !DOCTYPE declaration turns this mode on.
I strongly recommend using one of the DOCTYPE declarations that enforce this mode, because CSS errors which Internet Explorer would otherwise silently ignore, and which would cause problems for other stricter browsers are more likely to become apparent. See CSS Enhancements in Internet Explorer 6 on MSDN for further information.
If you have attempted to size content to fit the browser window exactly, turning on Standards Compliance Mode may cause problems. This is usually related to the use of height:100% as a style or height="100%" on a table or div ( or any other percentage height for that matter). To make this work properly the whole document must be sized. Here is one way to do this using a stylesheet:
html,body
{
height:100%;
}
It is a good idea to include a common Javascript file in all HTML documents. This allows a certain level of site maintenance to be done without the need for maintaining individual pages. For example all the DP4 help pages include BSSCDHTM.js. This script was originally generated automatically by RoboHelp, but it has been modified almost out of recognition - many changes to the documentation have only required a minor change to this file. To be really useful each web page needs to execute an onLoad function, because some changes to a page are not possible until it has completely loaded.
For example, web page authors commonly use the ALT attribute on IMG tags to specify a "tool-tip" title for the image. However, Mozilla does not display ALT attribute text like this, on the grounds that that is what the TITLE attribute is for. Obviously it would be very annoying to have to go through every single web page and duplicate the contents of the ALT attribute in the TITLE attribute. A simple bit of javascript fixes the problem:
// Ensure images with no title get some kind of tooltip
// Must be executed during or after onLoad() event
for (i= 0; i < document.images.length;i++)
{
im = document.images[i];
if (im.title=="")
im.title = im.alt;
}
|
The following snippet of Javascript arranges for tables to be striped:
if (document.getElementsByTagName)
{
var tableCol = document.getElementsByTagName("TABLE");
for (i = 0; i < tableCol.length;i++)
if (tableCol[i].className == "niceborder")
{
var rowCol = tableCol[i].rows;
for (j = 1; j < rowCol.length;j +=2)
rowCol[j].className = "darkrow";
}
}
|
Be wary of example Javascript code on MSDN and other Microsoft oriented web sites. Such code frequently uses Internet Explorer specific methods and properties that just don't work in other browsers. In many cases there are alternatives that are portable.
document.frames should be replaced by window.frames
Be wary of "default" parameters on DOM methods. Always specify all parameters - some browsers have different (possibly incorrect) default parameters on methods such as insertRow() and insertCell()
Do not omit units on positions,font sizes etc, either in style-sheets or scripting of style properties. Units are mandatory, and only Internet Explorer is forgiving (and not in standards compliant mode).
According to Microsoft you can call document.createElement with a parameter consisting of valid HTML, e.g. document.createElement('<p class="fred">')
This does not work in Mozilla and is probably non-standard. Use document.createElement("p") and set attributes using script.
Be careful that strings contained in script do not cause the script to end prematurely. For example
including document.write("</script>") in a script will cause your script to end in Konqueror. Instead write document.write("</scr"+"ipt>") or document.write("<\/script>"). In fact any string which looks like a closing tag is potentially dangerous.
Be very careful when scripting across frames - your code may well work until it is deployed on a web site. In particular you usually cannot get at the inside of a document in another frame, so, if all you need is to share a few variables, put them inside the window object of the frameset.
www.quirksmode.org is a valuable resource for discovering browser peculiarities.
Using DOM methods and properties is to be recommended. However, some non-standard properties are very widely supported, for example innerHTML works well in almost all browsers.
In general script should try to avoid executing different branches based on version or application name information returned by the Browser. It is all too easy for your script to be broken by a future version of a browser that is not backwards compatible, or by a browser that is masquerading as another. (Opera is especially prone to doing the latter).
Unfortunately there is one situation where you may need to find the exact version of the browser in use: sometimes a method or property is available in more than one browser, but is implemented very differently. For example the time at which changes to style information using script take effect changed in Internet Explorer 5.5 compared with earlier releases, and this may affect code that resizes elements.
Here is a function for reliably returning the version number of Internet Explorer (assuming you are sure it is Internet Explorer):
function msieversion()
{
var gAgent = navigator.userAgent.toLowerCase();
var msie = gAgent.indexOf("msie ");
if (msie > 0)
return gAgent.substring(msie+5,gAgent.indexOf(";",msie));
return ""; // not Internet Explorer
}
|
Do not assume navigator.appVersion begins with a correct version number. For example, in Internet Explorer 6, it begins with 4.0!
Opera is configured to identify itself as IE. You can test whether you are actually using opera by the following code:
function is_opera()
{
return window.opera ? true : false;
}
Whenever possible you should just test for the feature that you want to use. In addition, you can often add missing functionality to a browser, to avoid the need for writing mulitple versions of a function. For instance, you can implement the DOM getElementById() method very simply in older versions of Internet Explorer:
if (!document.getElementById && document.all)
{
document.getElementById = new Function('id', 'return document.all[id]')
}
Some people have tried to implement libraries of cross-browser compatible, devising a host of new objects and methods. This is a bad idea - whenever possible just implement any DOM methods you need that are missing in the browser of interest, or, when you are starting with IE specific Javascript, you may be able to add IE extensions to the other browser.
An example of the latter, is the extremely useful insertAdjacentHTML() method, which is for IE only. That and a number of similar methods are implemented in emulator.js, which can be included in HTML files that will use the method.
I recently converted my personal web site, originally created primarily for Internet Explorer 5, to work with IE6 in standards compliance mode. In the course of doing this I discovered some strange things:
Pages using filters and transitions on IMG elements as a mouseover effect have the effect of the transition ruined, through the image being unnecessarily completely repainted. This happens because Microsoft added a horrible popup "Image" toolbar which interferes with the page. Fortunately you can get rid of this toolbar by using a Meta tag:
<meta http-equiv="imagetoolbar" content="no">
If a page contains images sized as a percentage of width, then the image should resize. However this does not work properly unless the img is left aligned.