Easy GuideML
Created | Updated May 15, 2009
Easy GuideML
This article is to (hopefully) help people who are new to h2g2 and want to write smart GuideML pages without having to learn all that GuideML stuff.
What you need
The prerequisite is a word processor that can:
- Save what you write in clean, simple HTML
- Treat any file with an unrecognized extension as text
MS Word 97 or equal - but very definitely nothing more recent - fills the bill.
Now, all you have to do is create your masterpiece.
How To Do It
There are only a few simple rules to follow:
- Use only simple formatting such as bold or italic (forget underline) superscript or subscript - but don't apply any of it until after you've finished arranging your text.
- To make sure the tags for two formats applied to the same text nest properly:
- First select the text tight to the characters
- Apply the first format
- Now select it including the spaces at each end
- Apply the second format
- It helps to turn off automatic word selection – use the Shift and arrow keys only, rather than the mouse.
- Make sure you use indents rather than tabs.
- If you want to make lists, use Word's automatic numbering or bullets (I hate these features but for this job they're just what the doctor ordered!).
Of course, you may have trouble if you want to apply another one – but GuideML doesn’t seem to like underlines!
Saving your work
- Save your document as HTML. It will receive an extension ".htm"
- Close the file, shift to Windows Explorer (or your favorite File Manager) and change the extension to ".gml" for GuideML format.
Basic Tweaking
Back in Word, in the Open File Dialog Box select "All Files" and open your <document>.gml. Word treats it as a plain text file, so you can now see all the HTML and GuideML tags.
Now, use "Find-and-Replace" to change:
- "HTML" to "GUIDE" (only for the start and end tags of the document!)
- "<BR>" to "<BR/>"
- "<HR>" to "<HR/>"
That takes care of the basic differences between GuideML and HTML.
The Header Section
Between the "<HEAD>" and "</HEAD>" tags are some "<META... ...>" tags which show what software and type of coding was used to create the HTML document. GuideML doesn't need these, so the lines can be deleted. However, there is no harm in leaving the "<TITLE>... ...</TITLE>" line.
Checking for Errors and Polishing your Code
Now for the more complicated stuff: checking for overlapping tags, because GuideML's rule about non-overlapping tags can be a real pain.
By waiting until you finished arranging the text in your document before applying formatting, you should have largely avoided this problem - but there is no guarantee! And there is no substitute for going through the code line by line; but Word makes fixing errors easier by allowing you to select and drag errant tags to the required position (in the Editor you have to cut and paste).
When you're as happy as you can be, save the file (ignoring any warnings about loss of formatting when saving in text format). In the process it may acquire an extra ".txt" extension but you can easily get rid of that in Explorer. It won't matter anyway, because what you will do now is simply select all the text (or use [Ctrl]+[A], then [Ctrl]+[C]) and paste it into the h2g2 Editor, making sure beforehand that the format option button is set to GuideML and you have clicked the "Change style" button.
If you've missed any overlapping tags (or made any other errors), the Editor or Preview in Brunel will find and highlight them for you to fix. When you have done so - and previewed your page for the last time - don't forget to select all the fixed text in the Editor, then copy and paste it over the original in your ".gml" file (still open in Word) before saving it again.
Now you can post the page... ...and wait for the Peer Review team to get their teeth into it!
Points to Watch (Things I have found out when using Easy GuideML):
- If you format text exactly at the start or end of a line, you will get formatting tags overlapping the "<P>" or "</P>" line tags, so you'll have to watch for this (but Preview in Brunel will pick it up).
- If you follow the instructions above for applying two formats, the two sets of tags are properly nested... but the GuideML parser appears to ignore the spaces you get between the two sets of tags, so again you'll have to check and shift the spaces outside the tags.
- Some of the other tags aren't quite where you might expect; but since they don't overlap, they work OK.
Using later versions of Windows/MS Office
For those of you running Windows later than 98SE and Office later than 97, do not despair!
The separate Guide Entry "Easy GuideML Sample" was produced on a PC running XP Pro and loaded with MS Office 2003 and its version of Word. But I didn't use that.
Instead, I found an old copy of Word 97 in the "Program Files\Microsoft Office\Office" folder of a secondary hard drive that had once been the main drive on another PC, and started up the main Word program file - winword.exe - by double-clicking it in Windows Explorer.
For anyone else, just hunt around until you find a copy of this .exe file, which is all you really need, put it in any convenient folder and do the same*.
[*You'll have to clear the "Hide file extensions for known file types" checkbox in the View tab of Explorer's View, Folder Options dialog to make sure you're double-clicking the right file.]
When Word 97 starts up, it will look in the operating Registry on Drive C:, which will be set up for your current version of Word, and warn you that the installation files are corrupted and you should reinstall.
Ignore this warning, close the dialog box and 97 should start up just fine.
I did this, and then followed the Easy GuideML instructions to produce the Easy GuideML Sample page.
Using Open Office
Don't!
I loaded Open Office 1.0 to try using the Easy GuideML process and found the following problems:
- Open Office's basic format is XML. When you save your document as HTML, it has a "Doctype" tag before the "HTML" tag. The consequence is that, even if you change the filename extension, Open Office still opens the document as HTML, not as text.
- When you open the .gml file in Notepad, apart from the "Doctype" tag, you can see that the HTML is already "pretty" with complicated "SPAN" and font format tags, that are not what Easy GuideML is all about.
Good luck!
