Jos Kingston's homepage

File updated 22/03/05 10:41

What is htmltag?
System requirements
Htmltag philosophies
Conditions of use
Setting up the htmltag macro ready for use
Converting Word files with htmltag
Style conversion information
Heading 3 - set by default to generate top of file hyperlinks
Htmltag and hyperlinks
Converting tables with htmltag
Setting up a .css file for use with htmltag
Extracting images from Word files
Troubleshooting Information
Contact details

Clean, automated html production from simple Word files

Jos Kingston

What is htmltag?

When you save as a Web page from Word Microsoft assumes that what you want is to replicate as precisely as possible what the original Word document looks like. This applies whether you select either the "full" or "filtered" html option, But loyalty to individualised formatting is at loggerheads with the objective of producing clean, flexible html for a website where all pages take their text formatting specifications from a standard .css stylesheet. You need a different approach if this is what you want.

• Htmltag makes no attempt to be a "wysiwyg" (what you see is what you get) Word-to-html converter. Provided the user applies recognised style names in Word, radically different-looking Word documents can all be converted with htmltag to html files which are consistent across a website. Htmltag ignores user font choices (apart from bold, italic and hyperlinks) and takes no notice of such things as whether the document is laid out in columns, whether it includes page and section breaks etc. Text in text boxes will be ignored. This is not a limitation as far as the intention of htmltag is concerned. Htmltag is designed to produce html files which can take up whatever styles and formatting are desired simply through linking to a cascading style sheet.
• Various utilities exist for cleaning up Word html. Rather than cleaning up after the event, Htmltag takes the alternative approach of creating a clean html file from within the Word environment.
• Htmltag is a Word macro contained in a template (.dot) file. Using htmltag, simple Word documents like this one can be converted to clean html which will pick up all style formatting from a .css style sheet, and which will validate to xhtml 1.0 transitional. Note: htmltag will only produce validating htmltag reliably for users who familiarise themselves with its limitations and how to work around them. This requires a thorough reading of this document.
• Htmltag was developed to use with simple Word documents which consist primarily of text, such as this one. Regular tables will convert, but merged or split cells won't be correctly honoured. Currently pictures cannot be incorporated, although links to pictures can be included. See Extracting images from Word files for tips on acquiring pictures from Word files at optimum quality for use on Web pages.
• Htmltag will only work correctly if you have applied htmltag-recognised stylenames in your Word document. These include the default Word stylenames for Heading Levels 1-5, but you must also apply htmltag stylenames to numbered and bulleted lists, indents etc. (See Style conversion information) You will also have to learn the odd workaround for htmltag to work reliably.
• Htmltag automatically generates top-of-file hyperlinks from headings at the level specified in the macro. File update information is also automatically added at the top of the file. If you're currently viewing the html version of htmltaguser, this provides an example.
• Htmltag prompts the user to supply page title and keywords for html ouptut.

System requirements

• Windows 98: Htmltag was developed on a P2 running Windows 98 with 64 mb RAM. On this platform htmltag conversion of files containing large or numerous tables can be slow, but has always got there within a few minutes.
• Windows XP: No difficulties have been encountered running htmltag.
• Windows 2000: potential problems! On PCs at work (Sheffield Hallam University) with a standard Windows 2000 image, htmltag ran with no problems during the academic year 2003/4. Since the PCs were reimaged for 2004/5, again with Win2K but including some later Windows security patches etc, it has fallen over at the end of the macro when the final file is saved as html. This has also been reported on a tester's Win2K setup. Unfortunately it isn't possible for me to do any work to sort this out.
• Word versions: Htmltag was developed in Word 2002 and has not been fully tested on earlier versions, or Mac versions. It should run without problems in Word 97 onwards - please report any difficulties.

Htmltag philosophies

1. Most authors prefer working in Word

Even where documents are being produced with a view to use as web pages, it often makes sense to work in Word, and circulate documents in Word format for editing and proofing.

But difficulties can arise in situations where the final document is handed over to a separate Web team for html conversion. After they have spent time hacking around to produce a decent html version from the Word document, they have no inclination to do that work all over again every time the author makes changes to the document. Consequently, the html version becomes the definitive version, and the author no longer has the option to update and edit the definitive version in Word.

The solution to this is for the author to have the capacity to submit their material in squeaky-clean html ready to receive all its formatting from the website's standard css, and to be able to regenerate the html on the spot from within Word whenever changes are required to the document.

2. Best practice in formatting documents is essentially the same in Word and html

Consistent application of styles is the key, and htmltag requires this.

3. Learning to write and use macros in Word is empowering

It's partly in the hope of demystifying macros that htmltag is being distributed as code rather than a compiled program. There will be many occasions where customising the macro (for example to handle different stylenames) will make it a more useful tool.

4. Htmltag isn't designed for casual users

Htmltag isn't foolproof, and the process of learning to work within its limitations may take the user some time. It's probably not worth the effort unless you need to convert Word documents to html on a regular basis, and definitely not worth the effort unless you're prepared to apply styles consistently to Word documents.

Conditions of use

The necessary components can be downloaded direct from the link in the next section.

The macro code is entirely open source. However, Jos Kingston hereby asserts her moral rights of authorship as laid down in the 1988 Copyright, Design and Patents Act. These rights include the right to be identified as the author of htmltag and the right not to have this work "subjected to derogatory treatment"' - for example "addition, deletion or alteration prejudicial to the honour or reputation of the author."

This assertion is not intended to discourage customisation of the macro for personal use or to restrict its distribution. I have decided to make the macro freely available at this stage because I was diagnosed in December 2004 with a terminal cancer, and thought that a few people would find it useful or at least interesting.

There are some bits of code which I would like to have the energy to clean up a bit further, but unfortunately I don't! Details of known problems are included in Troubleshooting Information. If you do any work to improve the code, I would like to receive your revised versions of the macro. If you find the macro useful, please go to https://www.bmycharity.com/V2/joskingston and make a donation.

Please remember: it isn't the case that all Word files will produce validating html when you use htmltag. You must check your files with a reputable validating utility. The one at http://validator.w3.org/ is reputable, quick and easy to use, and lets you validate files stored on your local hard disk. Even where documents have been appropriately formatted using htmltag-recognised style names, there may be formatting quirks which I haven't encountered and which therefore aren't taken into account by the macro. If you use htmltag regularly, you should be able to sort workarounds in how you format your documents; or, if you have some understanding of VBA, customise the macro accordingly.

Setting up the htmltag macro ready for use

The macro, plus all the required htmltag style names, need to be available in a Word template (.dot) file. It can then be run from any Word document which is attached to the template. Before first use, you need to assemble the template file. This isn't being distributed ready-to-use for security reasons. Macros can be written to infect your PC with a virus, so encouraging people to download .dot files is generally a bad idea. Htmltag is intended for those who have a good level of computer knowhow, so if the instructions below are daunting you are recommended to decide now that it's not for you!

1. Download the three required files from here.
2. In Word, open the file htmltaguser.doc
3. From the Word File menu, select Save As. Set Save As Type to Document Template (.dot). Word will automatically set the Save As folder to its default template location. You can change this if you want, but in future you will find it quicker to attach files to the template if you leave it at the default.
4. Save this file with the name htmltag.dot. As long as you keep the .dot extension, you can call it something different if you want, but these instructions assume that htmltag.dot is the name of the htmltag template file.
5. Select all the text in htmltag.dot and delete it. This leaves you with a template file containing just the style definitions. Change these style definitions if you want your Word documents to reflect your own formatting decisions - it's the style names which are important to htmltag, not how the styles are formatted. If you want headers or footers included in your Word template, just set them up as usual. They will then appear in all Word documents based on the template, but htmltag will ignore them when you convert to html.
6. Check your Word configuration settings. If your Word configuration has been left at the default settings, new styles constantly get created "on the fly". Styles with names such as "Heading 1 char" are a symptom of this. It makes the whole process of using styles thoroughly confusing, and could also prevent htmltag working correctly.
   
   To prevent this, in Word make the following changes from Tools | Options:
   Tools | Autocorrect | Autoformat
   - under "Automatically as you type", switch off "Define styles based on your formatting"
   
   Additionally in Word 2002 and later: Tools | Options | Edit
   - under "Editing options", switch off "keep track of formatting"
   
   You may find that these changes don't take effect until you close Word and reload.
7. With htmltag.dot still your active file, from the Word Tools Menu, select Macro | Macros. Set Macros In to htmltag.dot. Now click the Create button. You must supply a name for a macro at this stage. It doesn't matter what this is - just x will do. In the following steps the macro "shell" which Word sets up for you automatically, will be replaced with the htmltag macro code.
8. When the Word Visual Basic window opens, delete all its contents so you have an empty window ready to paste into.
9. Open the file htmltagcode.txt, either in Word or in a text editor like Notepad. Select all the contents of the file, and copy it to the clipboard. Before going any further, general good practice when working with macros from "unknown" sources dictates that you should look through the macro code to satisfy yourself that there's nothng dangerous about it.
10. Return to the Visual Basic window in htmltag.dot, paste the htmltag macro text, save the file again, and close the Visual Basic window.
11. Htmltag can't run if you have Word macro security set to High. With htmltag.dot still open, from Tools | Options | Security, click the Macro Security button and select Medium or Low. If you select Medium, you will be prompted to OK whenever you open a file containing, or attached to a template containing, htmltag or any other macro.
12. The third file which you should have downloaded is htmltag.css - see Setting up a .css file for use with htmltag for further information.

Converting Word files with htmltag

You can use htmltag on existing files by attaching to the htmltag.dot template as described below. New files can be created based on the htmltag.dot template - this way, you will have all the htmltag-recognised style names available to you as you work and can thus avoid the pre-conversion preparation which is otherwise likely to be required.

• Before trying Htmltag on files which you have created, you are recommended to test out the process first on htmltaguser.doc (the original Word file you downloaded before saving a copy as a template as described in the previous section). This uses only htmltag-recognised formatting, and incorporates demonstrations of all htmltag capabilities. You may not appreciate these if you first try out htmltag on a document which hasn't been formatted for htmltag convertibility.
• Make sure that htmltag.css is in the same folder as the document you are converting. If you find that htmltag is useful to you, you can quickly "tweak" the macro so it's picked up from whatever folder location is specified there. See Setting up a .css file for use with htmltag.
• With the document you are converting open, in the Word Tools menu go to Templates and Add-ins. Click Attach, browse to the location of htmltag.dot, select and OK. Make sure that Update Styles is checked on. (This isn't the default setting.) You need to do this to make all the htmltag styles available in your document. Htmltag will terminate if they aren't.
• To create a new file based on the htmltag.dot template, in Word use File | New | Based on template (how you do this depends on the Word version). If you have installed your htmltag template in the default location for your Word setup, you will see it listed under General Templates. If you have put it somewhere else, in Word 2002 you will have to select New from existing document rather than New from template in order to browse to your .dot file.
• When you're ready to run htmltag on the file: From the Word Tools menu, select Macro | Macros. Set Macros In to htmltag.dot. You will see a long list of macros - these are all the sub-routines which are called from the htmltag main routine. Scroll down to htmltag, and click run.
  
  If you decide that you want to use htmltag regularly, you can speed up the process by adding a button to the toolbar. Open htmltag.dot and select the Tools | Customise menu. Click the Commands tab. Under Categories, scroll down to Macros, and set Save In to htmltag.dot. Under Commands, you should then see the full list of macros called from the htmltag routine. Click and drag the htmltag item from the list to the Word toolbar.
• Once conversion is complete, you will be returned to the original Word document and the html version will open in a browser window. If necessary on your own files, you would now correct the Word file and edit so it conforms to htmltag requirements, then run htmltag again to re-create the html file.
• Check that the file validates as xtml1.0 Transitional by going to http://validator.w3.org/ and uploading it. The html file has been saved at the same folder location as the .doc original.
• The first thing the htmltag macro does is to make a temporary copy of the Word document file to work with. Your original file isn't reopened again until conversion is complete. Consequently there is no risk of damage to your original file in the event of the macro terminating unexpectedly.

Preparing your own files for conversion with Htmltag

• If your document (and you) can generate a Table of Contents satisfactorily in Word, you're well on your way to being ready for htmltag conversion. As with TOCs, the key ingredient is use of Styles for Heading 1, Heading 2, Heading 3 levels - Htmltag can handle up to 5 heading levels, and the macro can easily be customised by a user who has some familiarity with VBA if more levels are required.
  
  How you set the formatting of these styles in your Word document version is entirely up to you. None of your preferences is taken into account when the file is converted to clean html - formatting for <h1>, <h2> etc. is defined by whatever .css stylesheet the macro is set to call.
• With a document which already has heading styles systematically applied using the default Word style names , the extra preparation you will need to do before running the macro, is to apply htmltag styles to any bulleted and numbered lists or indented text. See Style conversion information.
  
  If you have applied headings with non-standard style names: Note that in Word, you can use advanced search and replace capabilities to replace one style with another. An alternative approach is to rename styles to htmltag-recognised names before you attach your document to the htmltag template.

If you want to convert multiple documents for a website, before you convert:

• Organise the documents which you want to convert, into a folder structure which exactly replicates the destination website folder structure. Htmltag assumes that you have done this, and puts the .html version in the same folder as the .doc file, with no option to do anything else. (Unless you have the VBA knowhow to edit the macro.)
• Tweak the macro so that you are specifying the correct relative path for your site .css file. See Setting up a .css file for use with htmltag.
  Note: You will pick up the default browser styles settings when you view the html file unless it is attached to a .css file. Internet Explorer's setting from Tools | Internet Options | Accessibility | Format documents using my stylesheet is handy if you want to see what the .html looks like attached to your own .css file without any editing of the html file or the macro.
• Apply Heading 1, Heading 2 ... Heading 5 styles systematically to all headings.
• Make sure that all indented paragraphs, bulleted and numbered lists are defined with the appropriate style name - don't just leave them with Word's autosettings. See the following section.
• All style names which aren't recognised by htmltag will be converted to normal paragraph text.
• If your document includes tables, bear in mind that htmltag can only convert regular tables successfully. Merged or split cells will not appear correctly. Note also that all tables must be preceded and followed by a paragraph return formatted in Normal style.

Style conversion information

The following are htmltag-recognised styles. They will all be available when a document has been attached to the htmltag template with "Update Styles" selected. In Word, they can be formatted however the user wants to format them. In html, their formatting will be dictated by the settings in your .css file, which you can change as you wish.

Normal style + all unrecognised stylenames become paragraph text <p>.

Heading 1 - 5 styles become <h1>, <h2> etc.

Heading 1

Heading 2

Heading 3 - set by default to generate top of file hyperlinks

If you have a basic understanding of VBA, you will be able to tweak the htmltag macro to change the heading level from which top of file hyperlinks are generated. With more advanced VBA knowhow, you could edit the macro to generate top of file hyperlinks from more than one heading level.

Heading 4

Heading 5

The macro can be tweaked to add more heading levels if required. To be effective, all Heading levels which are included must be matched by style definitions in your .css file.

Indent style becomes <blockquote>.

Here's what indent style looks like.

You're especially likely to want to use it for quotations. Note that if you have defined a style for quotations in a Word document, you can switch them in one to htmltag Indent style using Word capability to Find and Replace styles. In the Search and Replace window, click Format and select Styles. Set to replace (say) Quotation with Indent, with the Find and Replace text boxes left blank.

Bullet style becomes <ul> (unordered list).

• Here's Bullet style.

Numlist style becomes <ol> (ordered list) Bulleted and numbered lists set to htmltag stylenames will maintain hanging indents after conversion.

1. Here's Numlist style...
   
   Numbered lists will all start at 1 after conversion. They can be quickly amended in (say) Dreamweaver.

Numlist2 style becomes <blockquote><ol>

1. Here's Numlist2. Note that it's a good idea to be sparing in your use of Numlist2 if you want your page to be usable at very narrow browser window widths - desirable if, for example, your page consists of software help.

Bulleted and numbered lists set from the Toolbar, without applying the Numlist or Numlist2 style, won't be honoured by htmltag. You can define formatting for Numlist and Numlist2 exactly as you want in the Word file, but Word (especially 2002) is very unwilling to forsake control over indenting of numbered lists and will probably cause you some grief whatever the formatting you specify.

The good news is that Htmltag will simply ignore how Word has indented your numbered lists - it just tags them according to which of the two numbered list styles you have applied. If you link your html file to a cascading style sheet, this can define indent positioning etc. for the <ol>, <ul> and <blockquote> tags.

Numbered lists converted by htmltag will always restart at 1 after a break. You need to tweak in Dreamweaver after conversion to reset. It would be possible to improve the macro to resolve this.

Word uses two different types of style - paragraph styles, which apply to a paragraph in its entirety, and character styles, which apply to selected characters within a paragraph. (Any string of text after which you have pressed the Enter key is a paragraph - heading styles are paragraph styles.) In addition to the paragraph styles described above, htmltag can convert the following character styles.

• Code character style becomes <tt> - teletype or typewriter text.
• Text set to the red or blue character styles is converted to red and blue font colour. This was included to provide a capability to highlight chunks of text for internal purposes (e.g. querying content) on local knowledge bases.
• Use character styles with great care. Tags will nest incorrectly if only part of a word is set to a character style.

Htmltag and hyperlinks

• Htmltag should convert all external hyperlinks in the Word file successfully, both to web addresses and to local files where relative path location is maintained. The hyperlink text doesn't need to be the url - e.g. click here will get to the specified hyperlink.
• Htmltag automatically creates top-of-file hyperlinks from headings at whatever level is specified in the macro. The process happens whether or not there is a Table of Contents in the Word document, and any existing TOC is simply ignored in the html version. The default for t.o.f. hyperlinks is Heading 3 level, and is what you see if you use the Word document version of this file as a demonstration. This can be altered if required by user tweaking the macro.
• Htmltag ignores bookmarks and links to bookmarks in a Word document. This could well be a simple bit of VBA coding for somebody to do and would be a great improvement on htmltag's Doclink character style described below.
• Htmltag's Doclink character style offers very limited capability for internal hyperlink navigation. If you use link text which corresponds exactly with a Heading 3 in your document - for example, a link to Troubleshooting Information , then setting the style for that text to Doclink will give you a link to that heading whether or not you have set it in Word to link to a bookmark on that heading.
• Unfortunately Doclink needs to be used with great caution. If your link text doesn't correspond exactly to a heading, you will get an illogical string of text instead of a link. It's all too easy to forget that if you change the wording of a heading and you have used doclink, you need to change the doclink text too.
  

Converting tables with htmltag

• Tables must be simple - no split or merged cells - to convert correctly with htmltag.
• Check tables carefully in the html version, especially top and bottom lines. If a table doesn't convert correctly, adding a blank line before and/or after the table will probably fix it.
• If a file contains tables, htmltag will prompt the user to specify border width. This will be applied to all tables in the file. Individual tweaking of table formatting will need to be done in Dreamweaver or by editing the html if required.
• Tables are converted with column widths specified in %

Here's an example table - blank cells are honoured as in the Word version.

Setting up a .css file for use with htmltag

It is assumed that htmltag users will understand the basics of using .css files to define styles. Your CSS file must include specifications for all the heading levels used by htmltag, and for lists, blockquotes etc. You can download a sample htmltag.css by right-clicking here. CSS files are simple text files and can be edited in Notepad - you can redefine settings however you want.

I have noted that the same .css style sheet gives different results in Firefox and Internet Explorer with regard to indentations for lists and blockquotes. Any illumination on this point will be welcome.

Tweaking the macro to call your own stylesheet

You can get straight into the macro code from any document which has been attached to htmltag.dot. You are advised to ensure that you have an unedited copy of htmltag to return to if necessary.

• Tools | Macro | Macros. Set Macros In to htmltag.dot. Find the routine called Tagheadinfo, and click Edit.
• Search in the routine for "htmltag.css" (without the inverted commas)
• Change to specify relative path and name for your .css file
• Save your changes, and save changes to template when prompted.

Extracting images from Word files

Htmltag simply ignores images when converting. If you want to include images in an htmltag-converted file, you'll need to quickly tweak the html in Dreamweaver or however. Htmltag does honour links to image files. Your work will be much easier if you bear in mind that that your working folder structure should exactly replicate the folder structure of your destination website.

In order to extract images at optimum quality from Word documents, the following knowhow is useful:

• Saving to Word html from 2002 (?2000) onwards offers the choice of a full or a filtered option. If you choose the full option, each image in your Word file will be saved twice - once at the original image dimensions, and once resized to required dimensions for the page layout. If you choose the filtered option, Word saves only the resized version. Consequently saving in Word full html and working from the fullsized auto-generated image file gives optimum control over final image quality. If your only source of the images within a document is the Word file, you'll normally find that you can extract perfectly satisfactory .jpg images this way. Watch out though for any pictures which have been generated by Word's save as Web page, in .gif format. Quality can be very poor. You can often work round this by using one or other of the techniques described below.
• Drawing objects in a Word file may not convert to a single image file. It's best with drawing objects to convert to bitmap format first. Do this by selecting and cutting the object(s), then Edit | Paste Special to put them back in a user-selected format. Select Picture (jpg) for photos; Picture (png) for drawing objects. Note that Microsoft likes to do nasty things with gif format.
• Microsoft Photo-Editor is part of the standard Office installation (Start | Programs | Microsoft Office Tools) which has special capabilities in terms of retrieving bitmap images from Office files. When you copy a bitmap from Office software and paste as new image into Photo-Editor, the dimensions of the image as originally inserted into Word are maintained. For optimum quality control, save as TIF from Photo-Editor then save to high-quality jpg, gif or png as appropriate from Photoshop, PSP, Irfanview or other software which permits user selection of settings.

Troubleshooting Information

Under Windows 2000, Htmltag terminates at the end when text file is saved as html

On PCs at work (Sheffield Hallam University) with a standard Windows 2000 image, htmltag ran with no problems during the academic year 2003/4. Since the PCs were reimaged for 2004/5, again with Win2K but including some later Windows security patches etc, it has fallen over at the end of the macro when the temporary text file generated by htmltag is saved with the .html extension. This has also been reported on a tester's Win2K setup. A simple workaround in the macro may well be all that is needed, but unfortunately it isn't possible for me to sort this out. Later Win 2K/Word updates may have resolved the problem, which isn't present in XP.

If the macro terminates this way, it's probably best to give up on it unless you're a VBA whizzo. You may find that you can retrieve the html code from the temporary file temptext.txt which is generated by htmltag, and should be available in the same folder as the file you have converted. (If htmltag runs correctly, this file is automatically deleted right at the end.) You can quickly check that this is likely to be good html by whether there's anything after the closing </html> tag - if there is, the conversion process didn't complete before the program termination.

Program terminates: Requested member of the Collection does not exist

Program terminates and window opens with this message. This will happen if not all the htmltag styles are available in your document. This is likely to be the case if you run htmltag on existing documents not initially based on the template htmltag.dot, and you didn't check the "Update styles" box when you attached the htmltag template to your file.

Solution: end the program, close the file tempdoc.doc, and return to the file which you were running htmltag from. This will not have been changed. From Tools | Templates and Add-ins, check the Update Styles box and OK. You can now run htmltag again, and all the required styles will be found.

This behaviour has deliberately not been eliminated so that users are forced to work with the htmltag macro as the author intended.

Program terminates with "String Parameter too long" message

This happens if you set up a doclink to the last of the hyperlink-generating headings in your file (by default, the last heading 3). The reason is because the doclinks part of the macro works in a silly way which needs changing. (See later in this troubleshooting section.)

Solution: end the program, close the file tempdoc.doc, and return to the file which you were running htmltag from. Workaround by avoiding internal links to the last section for now, and re-run htmltag.

Bulleted and numbered lists aren't appearing as hanging indents

You must apply htmltag's stylenames to all lists in order for them to be tagged as lists during html conversion.

Solution: edit your Word document to set lists to recognised htmltag styles. (Bullet, Numlist, or Numlist2.) Note: This is a much quicker process than the sorting out you're likely to need on lists in Dreamweaver if you currently generate Word html then import into DW to clean. Further note: numbered lists not holding their formatting are a common cause of grief in Word (especially if you transfer between different PCs - apparently this is because some Word numbered list settings are stupidly held in the PC's Registry). Unfortunately you may encounter irritations when you set numbered lists to htmltag styles. But however stupid Word makes the indentation, formatting of Bullet and Numlist styles will be consistent (as set in the .css) in the htmltag version.

All new lists restart at number 1

This is a limitation of htmltag which can be quickly corrected where required by editing the html in Dreamweaver or however.

Numbers aren't being carried through from outline numbered headings

In Word, the numbers as such aren't part of the file's text if you have used outline numbering - they are auto-generated fields in the file.

Solution: It's useful knowhow that headings set to outline numbering are converted into hard numbers if you save the file in Word 2 format. I have written an additional pre-conversion macro making use of this Word "feature" to run pre-htmltag. Outline numbering in your original Word document is maintained. But this needs customising to suit different usages of outline numbered styles. It isn't anticipated that people without macro knowhow will be able to make use of it. Click here for more information.

End paragraph tag missing prior to a table, hence subsequent code doesn't validate

This may happen when there isn't an empty line formatted in normal style between a table and the text preceding it. The missing </p> can lead to a host of validation errors in subsequent html. I hope that I have fixed the problem in most instances, but watch out for it.

Solution: edit your Word documents to add a carriage return before all tables.

First line of text directly following a table gets included in the table, and code consequently doesn't validate.

This may happen when there isn't an empty line formatted in normal style between a table and the following text, but I hope that I have fixed the problem.

Solution: edit your Word documents to add a carriage return after all tables.

Blank lines in top-of-file hyperlinks

This happens if a blank line has been formatted as a heading style at whichever level is set in htmltag to generate the file hyperlinks. (By default, Heading 3 level.) Note that you will similarly get unwanted results if you generate a Table of Contents in Word from a file with blank lines formatted as heading styles.

In general, blank lines set to any style other than Normal are bad news as far as htmltag is concerned and can cause formatting failures in conversion.

Solution: edit your Word documents to remove or set to normal style, any blank lines set to a heading style.

Incorrect nesting of bold and italic tags causing validation errors.

This was happening on this troubleshooting section of document where I had the space following "Solution:" set to italic.

Solution: In this case, with the colon and space after "Solution" set to not bold, not italic, correct nesting was achieved.

The "Doclink" style is unreliable and cumbersome as a way of setting internal document links.

Solution: Doclink is indisputably basically naff. Inevitably if you use the Doclink style, , at some point you'll change a heading without remembering to change all doclink instances which link to that heading. And then things will go haywire - you'll get a chunk of the wrong text plonked in instead of a doclink. Check the html version carefully wherever you have linked to an internal heading. Other points about htmltag doclink style: it usually creates internal links correctly in the middle of a paragraph but sometimes doesn't work correctly if the link is on a line of its own.

A competent VBA programmer could almost certainly add the capability to convert bookmarks to internal html links, hence eliminating any temptation to use the awful doclink.

Hyperlinks go "out of sync" - appear in the wrong places and to the wrong links

This has been encountered where the problem was caused by a graphic in the Word document containing a "behind the scenes" internal hyperlink. If the document was set to view Field Codes (Tools | Options | View), the "rogue" graphic was no longer displayed but appeared as a field code {SHAPE ..\*.MERGEFORMAT}.

Htmltag has not been tested with Word documents containing pictures other than inserted bitmaps, which are ignored. "Rogue" behaviour as described above has been replicated where graphic objects are nested within one another (e.g. a picture fill in a drawing shape), and these objects are cut and pasted. On the basis of this experience, similar results may occur where a document contains complex graphic objects (charts pasted from Excel, drawing canvas objects etc.)

Solution in this particular case was to delete the field, then re-insert the graphic from file and check it no longer showed as a field. (Paste Special to a bitmap format didn't stop the graphic behaving as a field.) Htmltag conversion then worked correctly. Specific "shape - mergeformat" behaviour could be addressed by simple additions to the macro if htmltag was being used in contexts where this limitation was a regular nuisance. However htmltag is only intended for use with simple Word files which contain no more in the way of graphics than inserted bitmap images.

My html doesn't validate - complains about "&"

Htmltag converts all &s in the text to &amp. The problem will arise if, when htmltag prompts you for page title, you add a title which includes & - validation will fail. Things will be fine if you type &amp in the title prompt, not just &.

My html validated straight from htmltag, but not after I'd tweaked it in Dreamweaver

Watch out with Dreamweaver for default tagging which doesn't validate to xhtml 1.0 Transitional. In particular, note <br> as opposed to <br />; absolute height specs in tables. Dreamweaver will also strip out the / which is required for validation as xhtml 1.0 transitional, from any <head> items you edit. For example, this happens if you attach to your .css within Dreamweaver (which you may wish to do for the sake of greater "wysiwyg" in Dreamweaver). There may be ways to avoid this in Dreamweaver versions later than 4 - this hasn't been tested.

Contact details

Jos@Joskingston.org

Please get in touch if you find htmltag useful or have made any improvements to the macro - I may not be dead yet! You can quickly check at http://www.joskingston.org/Terminal/index.html. As at December 2005, I can see from my web statistics that a steady trickle of people are downloading the macro and it would be very interesting to know how they get on with it. However, I don't intend to undertake any further programming work on htmltag myself, and I'm unlikely to be able to provide troubleshooting support. The biggest frustration to my mind is that as it stands, htmltag is unusable with versions of Windows 2000 where post-2003 security patches have been installed, despite being perfectly fine with XP. I have a feeling that a quick VBA tweak could provide a workaround and it's really most frustrating that my brain simply can't bend itself round such things any more!