VTML Validation

On this page:

Background
Limitations
Assumptions
Installation
Version
Usage
Single configuration
Registry tip
Download
Feedback

When version 3.0 of Allaire HomeSite was released, some important changes were welcome and expected because they were announced well beforehand. But after returning from my vacation, the biggest surprise for me was the visual editors, once I realized what they meant in terms of flexibility and a means to standardize the way your code is formatted. I jumped in with both feet. I wanted... I wanted a lot of things, and as usual when I get my hands on a new software tool I wanted to do more than was actually possible. I always seem to run into walls. Never mind, VTML, the markup language with which the visual tag editors are defined, is still a very new language and I have great hopes for it.

Of course I immediately started creating my own set of visual tag editors, based on the ones supplied by Allaire, but with additional support for some HTML 4.0 (notably attributes supporting StyleSheets) and supporting my own coding standards. This project isn't quite finished yet, but when they're done they'll be posted on this site. I also soon ran into a difficulty: it's very easy to make a mistake such that HomeSite doesn't understand your code anymore. When HomeSite is asked to display a dialog with an error somewhere in the EDITORLAYOUT section, it gives up and just says "Huh?!" (it displays an error message without any message). Not very helpful, and where is that mistake? On one occasion I just could not find it even after over an hour comparing it with the original; ultimately I gave up and started over. What a waste of time...

A discussion on a mail list about the qualities (or not) of Al Wiersch's CSE HTML Validator which now comes bundled with HomeSite triggered the idea: would it be possible to teach CSE to validate VTML?

After an initial experiment I found that VTML validation is quite possible. With some notable limitations:

• CSE has some rules built-in that cannot be overruled, basically because it expects HTML (with some possible extensions) and not a totally different markup language. For example, in VTML files you'll find a convention to end WIZSET statements with a space before the final >; that enhances readability but CSE flags this as an error;
• VTML uses quotes around a lot of the code that is written out, and not only attribute values; CSE will normally flag these as an error as well but you can turn this off in the Program Options. You'll probably want to turn this back on before validating HTML however.
• When you validate a tag editor file for a VTML tag, CSE will get awfully confused about where the tags end; ignore such messages.

You'll have to use your common sense to use the results of the validation!

I've had to make a number of assumptions in creating the configuration for CSE 3310. You may or may not agree with them. Here are some of the important ones:

• Integer attribute values may or may not be quoted;
• String attribute values should always be quoted, including special values such as "MAXIMUM";
• Some attributes are not (yet) documented in Allaire's help files about VTML, so I've had to make assumptions about possible attribute values based on what I found in the VTML files accompanying HomeSite 3.0;
• For which attributes are possible at all, I've used both the help files and the actual .vtm files to deduce what's possible; they don't always agree. (I'm working on a set of updated help files that at least correspond with what is actually being used in HomeSite's VTML files; when they're reasonably complete I'll post them on this site.)

Want to give it a try? Download the zipped VTML configuration file and install it. Basic installation is quite simple: unzip the zipped configuration file VTMLval25.cfg into any directory you like. The most convenient place is probably the same directory where your copy of CSE lives.

The VTML validation configuration file is based on the configuration file that comes with CSE version 2.51. As long as the format of the configuration files does not change, it should be usable with later versions as a separate configuration file for just VTML validation. The current version of the VTML configuration file should be considered an alpha release. I'll need feedback to make it better!

The configurations for how CSE does its work is basically stored in two different places. How the program behaves is stored a set of String values in the Registry. The actual validation rules (the "knowledge" that CSE uses to validate your files) are stored in a configuration file; the the default configuration file is called htmlval25.cfg and it is installed in the Validator's program directory.

Because of the limitations mentioned above, you'll probably want to adjust some of the program options before validating VTML; because these options are stored in the Registry rather than in the configuration file, you'll have to do these adjustments yourself. Don't forget to set them back to what you had before when you want to use the program to validate HTML again!

There are two ways for using the VTML validation configuration file:

• With CSE HTML Validator as a stand-alone program;
• From within HomeSite while you're working on the .vtm files.

Since for each method there are slightly different ways to set it up and use it, I'll outline both below.

Using CSE HTML Validator as a standalone program to validate your VTML files.

1. Start CSE 3310. (Tip: make a shortcut to it in the HomeSite group of your Start menu.)
2. Press Alt+F2 or go to the Drag and Drop menu item and make sure the program is set to 'Use validator on Dropped Files'.
3. Choose Settings -> Load Configuration... and use the File Open dialog to navigate to where you've installed the VTML configuration file (VTMLval25.cfg).
4. If you want to adapt the program's behavior for VTML validation, do the following:
   • Go to the Program Options dialog by pressing F4 or choosing Settings -> Program Options...;
   • On the Program tab, UNcheck 'Autosave Program Options' so your options will not be automatically saved to the Registry;
   • You may also want to change the Output Viewer and Document Editor to the editor you normally use (if you use something else than Notepad, that is);
   • On the Validator tab, you'll probably want to increase the number of errors and warnings displayed; if you don't, CSE may reach one of those limits with some of the messages I could not suppress (see Limitations above) before it's done validating your VTML file;
   • Also make sure you check both 'Allow spaces around "="' and 'Ignore all quotation requirements';
   • On the Logging tab, you may want to enable logging;
   • Press OK; you'll see a message "The default HTML Configuration file has changed. Do you want to load it now?". Press Yes, then press OK to confirm the message box "The HTML configuration has been successfully loaded". (You should get this message, anyway - if not, there's something wrong...);
5. Now you can use Window's Explorer to highlight any .vtm files (one or more at the same time if you want) you want to validate, and drag and drop them on CSE 3310's open window.
6. When you close CSE 3310, you'll get a message: "The program and/or validator options have not been saved. Do you want to save the current options before exiting?". Press No to prevent the temporary settings for VTML being saved into the Registry.

Using CSE HTML Validator as integrated with HomeSite.

If you normally use HomeSite as the editor for your VTML files, you can also use CSE with from within HomeSite with the VTML configuration file. It's just slightly more roundabout since HomeSite does not have a complete interface to all of CSE 3310's menu choices. (in fact, CSE only provides an interface for 'Program Options' and 'HTML Configuration Editor', so that's not Allaire's fault.)

1. Start HomeSite and load the VTML files you want to work on and validate.
2. If CSE is already open, close it: you cannot use the program from HomeSite when it's opened as a standalone program.
3. HomeSite does not provide an interface to CSE 3310's menu option to load a different Configuration File; luckily there's a workaround through the Program Options for which HomeSite does have an interface; you'll probably want to adapt the program's behavior for VTML validation anyway, so do the following:
   • Go to CSE's Program Options dialog by choosing Options -> Validator Settings -> Program Options...
   • On the Program tab, do not uncheck 'Autosave Program Options': when CSE is called from HomeSite it looks at the Registry settings anyway so they have to be changed to point to the VTML configuration file before you can do VTML validation from within HomeSite.
   • Still on the Program tab, change the Default HTML Configuration file to the VTML configuration file (you can use the '...' button to navigate to it with a File Open dialog)
   • On the Validator tab, you'll probably want to increase the number of errors and warnings displayed; if you don't, CSE may reach one of those limits with some of the messages I could not suppress (see Limitations above) before it's done validating your VTML file
   • Also make sure you check both 'Allow spaces around "="' and 'Ignore all quotation requirements'
   • Press OK; you'll see a message "The default HTML Configuration file has changed. Do you want to load it now?". Press Yes, then press OK to confirm the message box "The HTML configuration has been successfully loaded". (You should get this message, anyway - if not, there's something wrong...)
4. Now work on and validate any VTML file from with HomeSite just like you normally work with HTML files
5. When you're done, don't forget to change CSE's Program Options back to how you normally have them for HTML validation since these are stored in the Registry (see tip below for a shortcut to doing this!).

Using the VTML configuration file as your only configuration.

It's possible, but I don't advise it... Why? And How?

My VTML configuration file is based on the standard configuration file that comes with CSE HTML Validator version 2.51 (the version included with HomeSite 3.0.1 beta 2). At the moment of writing, CSE version 2.52 is already out, and 2.53 is on the way, with updated configuration files. My VTML configuration should work with the newer versions of CSE but to avoid conflicts with both later versions of the configuration files and with HTML validation, I've disabled all categories except the new 'VTML (HomeSite)' category. That way, you can continue to switch between my VTML configuration file and the standard HTML configuration file that comes with CSE 3310, even with later versions. You can also keep your own updates of HTML validation configuration separate from the VTML configuration file.

If you still want to use only one configuration file for everything, you could rename the file htmlval25.cfg to something else, and rename my VTMLval25.cfg to htmlval25.cfg. Then you'll also have to re-enable all categories besides 'VTML (HomeSite)' using the Configuration editor. And you'll still have to (temporarily) adapt the Program options when doing VTML validation anyway.

Like I said, not recommended. It's much better to keep VTML validation separate from HTML validation and future updates for it.

If you're using the VTML validation from within HomeSite, it's handy to be able to save your current (normal) Program Options and quickly restore them. Here's how to do that:

1. Start the Registry editor (choose Run... from Window's Start menu and type 'regedit', then press OK).
2. (In case you've never used the Windows registry editor before: You'll see a split window much like an Explorer window, with a tree view on the left, and details on the right. Click on '+' and '-' to expand and collapse branches.) Navigate to HKEY_CURRENT_USER\Software\Allaire\Studio and highlight the key called HTMLValidator.
3. Now choose Registry -> Export Registry File... from the menu and choose a name and location for the file that will be created. (Hint: call it NormalOptions and store it in CSE 3310's program directory; the extension .reg will be added automatically.)
4. Close the registry editor.

Now, whenever you want to restore the original Program Options for CSE 3310, all you have to do is double-click your saved registry file (NormalOptions.reg).

There are two separate files available for download:

VTMLval25.zip (25.9 Kb)

This unzips to VTMLval25.cfg; see installation instructions above;

VTMLvalDoc.zip (17.0 Kb)

This page (in a local version) together with its StyleSheet and graphics; unzip into a directory off your HomeSite Help folder or the Validator folder. (Note: when using HomeSite's own internal browser, StyleSheets are not active.)
(updated for new domain 1998-04-28)

Since the current version of the VTML validation configuration file is still highly experimental (yes, it's no more than an alpha), I'd appreciate your feedback:

• Are the instructions clear enough? If not, where do you get stuck or where did you have trouble?
• Are there things that don't validate that you think are quite correct?
• Are there things that do validate but are actually an error?
• Any suggestions?

Send your comments to: Comments about VTML Validation