GuideML Syntax
Created | Updated Nov 22, 2011
This document describes the structure of a typical GuideML article, the syntax of GuideML, and how to incorporate HTML tags into GuideML articles.
The Structure of a GuideML Article
The start of every GuideML article should begin with a <GUIDE> tag. This lets the parser1 know that the article is written in GuideML.
Next comes the one section you must have - the <BODY> section which contains the main text of the article. So a GuideML article with no content in it would look like this:
<GUIDE>
<BODY>
...article body...
</BODY>
</GUIDE>
Other sections you may see are <INTRO> and <REFERENCES>.
Within the <BODY> element you can put whatever text you want, and you can use other elements to add more structure and functions to your article. A complete list of GuideML tags can be found at the DNA GuideML Clinic.
GuideML Syntax
Because GuideML is an XML (Extensible Markup Language) it has to obey certain syntactic rules that HTML can safely ignore. If you try to create a GuideML page that's illegal, our GuideML parser will complain and not let you create it. So here are the rules.
The comment syntax is <!-- this is a comment -->. GuideML does not allow double hyphens inside a comment block, so <!-----------this is a comment -------------> for example, will fail spectacularly2. This is a nasty one so it's best to avoid comment blocks altogether.
The ampersand character & will cause problems in GuideML pages. You should use the code & wherever you need the & character (including in URL arguments to the <LINK> tag).
All tags have to be closed. This means that for every opening tag - <P> for example - there has to be a corresponding closing tag - </P> in this case. This is the biggest cause of GuideML syntax errors.
Empty tags (i.e. those with no content, like line breaks <BR> and horizontal lines <HR>) must also be closed, but there's a shortcut you can use. Putting a slash at the end of the tag, as in <BR/>, closes the tag automatically: <BR/> means the same as <BR></BR> (though the latter is not legal in GuideML). This closure can also be used with empty tags that have attributes, such as the <PICTURE> tag, as in <PICTURE BLOB="B123456"/>.
GuideML tags cannot overlap, so you cannot have something like <P><B>...</P></B> - instead it has to be <P><B>...</B></P>. Like the layers of an onion, the tags 'pad' the enclosed text with 'coats' one 'over' another, so that a one-line paragraph with the the coding:
<P><I>Water, water, everywhere, and not a drop to drink.</I></P>
would appear like this:
Water, water, everywhere, and not a drop to drink.
But the GuideML wouldn't work if you marked up the text thus:
<P><I>Water, water, everywhere, and not a drop to drink.</P></I>
because the <P> and <I> 'coats' overlap, rather than enclosing one another.
The tags you use should be capitalised. This is for a technical reason3. Don't worry about having to change all the GuideML in all existing articles from lower to uppercase, though, because the parser will cope with both types. However, getting into the habit of putting your GuideML tags into uppercase letters is A Good Thing.
Attribute arguments must always be surrounded by double quotes, so for example <P ALIGN=RIGHT> is invalid GuideML, but <P ALIGN="RIGHT"> is correct.
Only non-numerical entities can be used - such as π - as the XML processor eats up numerical ones before the h2g2 parser can get its hands on them. If you want to put in a numerical entity, don't use π (for example), but use the <ENTITY> tag like this: <ENTITY TYPE="960"/>. See the article on Special Characters for more information.
Other Tags
A subset of HTML tags can be used in GuideML, as long as the syntactic rules above are followed. However, only tags which are documented in the DNA GuideML Clinic are guaranteed to work in the future.
