Converting Framemaker documents into HTML

This document has been written with the specific needs of The Parallel Computer Centre at Queen's in mind; reference is made to resources on the PCC network and the conversion rules are tailored to the two main document types the PCC uses, i.e. OHP slides and student notes.

Setting up the FrameMaker documents

The Conversion process uses up a great deal of Hard Disk space. So firstly we need to make a copy of the FrameMaker file(s) in a directory where there is no very restrictive quota restraint.
WebMaker 1.4, which we will use for the conversion, cannot convert FrameMaker documents directly. What we need to do is convert the relevant file(s) into Maker Interchange Format (MIF) files. The way we do this depends on whether we are converting a single file or a book of files:

Conversion of a single Frame Maker document
1. Open the document in FrameMaker.
2. Save the document using 'Save As...' from the 'File' menu
  It is important that you select 'Maker Interchange Format' for the file Format, and you give the new filename the suffix .MIF.
Conversion of a FrameMaker Book of documents
1. Open the Book in Frame Maker.
2. In turn, open each document in the Book, saving each as described above.
3. Finally, we need to save the Book (the file which orders the documents which makes up the Book):
  1. Select 'Save As...' from the 'File' menu (on the book)
  2. Choose 'Interchange (MIF)' for the Format
  3. We cannot change the suffix from book, so alter the filename in some other way (perhaps adding MIF before the dot). In this way you don't wipe over your original Book file.

Creating a WebMaker Configuration file

Firstly, run the configuration file creation program wmconfig. The syntax for this program is:
wmconfig -c <config file name> <file name>
where <config file name> is the name you wish to give to the generated configuration file (This should have the suffix .wml), and <file name> is the name of the file / book you wish to convert.

Now this generated configuration file wil convert the file(s) into a single HTML document with all text rendered exactly the same. So we need to modify the file to suit our needs.
Firstly we need to stick in some NODE rules, which define how the document is to be split up. These NODE rules should be the same in all PCC documents. So I have included them here. Copy them into the configuration file (filling in the relevant fields) in an appropriate place (the actual position should be towards the top of the configuration file).

VARIABLE @NavPanel
NODE FirstPage
{
  TITLE "<Name of document structure>, QUB"
  HEADER
  {
  @NavPanel=concatenate(button("[Next] ",    filename(next),    "[Next] "    ),button("[Previous] ",filename(previous),"[Previous] "),button("[Top] ",     filename(top),     "[Top] "     ));
  write(*,link("The Queen's University of Belfast","http://www.qub.ac.uk/"));
  write(*,hrule());
  write(*,paragraph(concatenate(image("http://www.qub.ac.uk/graphics/crest.gif",bottom),image("http://www.pcc.qub.ac.uk/gifs/pcclogo3b.gif",bottom),link("Parallel Computer Centre","http://www.pcc.qub.ac.uk"))));
  write(*,paragraph(@NavPanel))
  }
  FOOTER
  {
   write(*,hrule());
   write(*,toc(2,global));
   write(*,hrule());
   write(*,@NavPanel);
   write(*,hrule());
   write(*,address(concatenate(" All documents are the responsibility of, and copyright, © their authors and do not represent the views of The Parallel Computer Centre, nor of The Queen's University of Belfast.",break(),"Maintained by Alan Rea, email ",link("A.Rea@qub.ac.uk","mailto:A.Rea@qub.ac.uk"))));
  }
}

NODE BasicSection
{
TITLE concatenate("<shortened title> ",headingtext(current),", QUB")
HEADER
	{
	@NavPanel=concatenate(button("[Next] ",    filename(next),    "[Next] "    ),button("[Previous] ",filename(previous),"[Previous] "),button("[Top] ",     filename(top),     "[Top] "     ));
	write(*,link("The Queen's University of Belfast","http://www.qub.ac.uk/"));
	write(*,hrule());
	write(*,paragraph(concatenate(image("http://www.qub.ac.uk/graphics/crest.gif",bottom),image("http://www.pcc.qub.ac.uk/gifs/pcclogo3b.gif",bottom),link("Parallel Computer Centre","http://www.pcc.qub.ac.uk"))));
	write(*,paragraph(@NavPanel))
	}
FOOTER
	{
	write(*,hrule());
	write(*,@NavPanel);
	write(*,hrule());
	write(*,address(concatenate(" All documents are the responsibility of, and copyright, © their authors and do not represent the views of The Parallel Computer Centre, nor of The Queen's University of Belfast.",break(),"Maintained by Alan Rea, email ",link("A.Rea@qub.ac.uk","mailto:A.Rea@qub.ac.uk"))));
	}
}

Other Alterations which would need to be done are as follows:

Unless you want all text to be rendered in exactly the same way (which, believe me, you don't), you need to alter the paragraph rules. Look in some of the previously coverted document's configuration files for examples of how to do this, and copy & paste their conversion rules (remember though, to only copy in conversion rules from the same type of document; don't use the conversion rules for OHP documents for student notes conversion and vice versa). Only paste in rules which you are sure you want; it is a good idea to look how each paragraph looks in the original FrameMaker document and convert with a similar aesthetic in mind.
Alter the Character formats according to taste, retaining the spirit of the original document. An explanation of how to do this is contained in section 6.5 of the WebMaker user guide.
Add Character conversion rules for peculiar untagged character highlights. These are where, in the original FrameMaker document, a word or phrase has been made Bold, Italic or has a different font to the rest of the paragraph, without making the changes part of a new character style. These conversion rules are contained in section 6.5.2 of the WebMaker user guide.

Running Webmaker

Once you have made your configuration file, you are ready to run WebMaker itself.
This is done with the following command:
webmaker -c <config file name> <file name>
i.e. exactly the same as running wmconfig, but replacing it with webmaker. The generated HTML file (without graphics) are put into the directory wmwork/www/ . It is useful at this stage to check these files (on any WWW browser) to make sure the results are satisfactory. If not, you need to alter the configuration file further, making the necessary modifications, and then re-running webmaker.

Running the graphics conversion package

Making sure you are in the directory where the rest of the conversion has taken place (not, for example, wmwork/www/), you can run the graphics program by typing:
wmgraph -G -V -n <name>
where <name> is the prefix to the original file / book name
i.e. if you are converting the file sample_file.MIF, <name> would be sample_file
or if you are converting the Book sample_bookMIF.book, <name> would be sample_bookMIF

For most documents, the Graphics conversion program is very slow and grinds your machine. It is probably a good idea to have it running overnight.

Cleaning up the created files

WebMaker creates HTML files, but not great HTMl Files.

We want to be proud of out HTML. It should be a beacon in the darkened world of Mediocrity. So we need to make a few alterations to the files created:

For cross-referencing, WebMaker inserts <a name=".."> tags in the documents it creates. However it doesn't close them. So we have a program on the system to do this for us. To use this program, do the following steps:
1. Go into the directory wmwork/www/
2. Move all the HTML files into another directory, perhaps one you create called copy, i.e.:
  mkdir copy mv *.html copy/
3. implement the program name_closer using the following command:
  name_closer copy/<file> > <file>
  where <file> is one of the HTML files.
4. Repeat this for all HTML items (which you moved into the copy directory). The directory should now contain the same files as it did before, albeit each file being slightly bigger
We now want to open each file up to perform a few modifications manually. The Editor you should use is AsWedit.
When you open each file, in turn, in AsWedit, it will check them automatically and provide suggestions as to the modifications necessary to make the HTML correct. Be very careful about following the suggestions. Most of the time it is a very poor choice. By not following the suggestion, AsWedit reverts to non-HTML mode, in which you can manually make the modification required. Examples of necessary modifications are given below:
- WebMaker often inserts spurious end-tags. Often, you can just delete these as AsWedit suggests.
- Lists are converted poorly; it will certainly produce bad results if in the list you are using more than one style. These have to be adjusted manually. DO NOT just delete items as AsWedit will suggest.
- In converting the OHP slides, WebMaker will also make redundant headings corresponding to the headings at the top of every slide. These need to be deleted in the text, as well as their entries in the manually generated table of contents in the first page of the document web.
- You need to insert the following line as the top line of the HTML document. This is to ensure compatibility with future browsers:
```
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
```
- Finally, you will need to look through the pages (on a browser, not an editor) to see if any parts look a little odd, and then manually correct these. This would include a redundant table of contents which was included in the original document but which is superseeded by the automatically generated table of contents. Also remember to remove any references which are 'media-sensitive' such as on page.... It is good practice not to use such phrases in you original document, and then this problem does not occur.
Finally, as a last (and comprehensive) test, we will use the program html-check. While we are in the directory containing the HTML files, type the following:
html-check *.html
If the HTML is correct each file will return the phrase Valid... as it is addressed in turn by the program (it could produce a library warning, but as long as it returns Valid... you need not worry). If it comes across some mistakes, it will return the position in the text file where these occur, along with an idea of what the mistake is.

Documents Created!

After having passed all these tests, your finished documents are created. You can now copy them into their final resting place. Please also copy into the same directory the final configuration file you used (with all modifications) so everybody else in the future can benefit from your experience.

Written and Compiled by Ben Aldred
All documents are the responsibility of, and copyright, © their authors and do not represent the views of The Parallel Computer Centre, nor of The Queen's University of Belfast.
Maintained by Alan Rea, email A.Rea@qub.ac.uk