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:
Other sections you may see are
<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.
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
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
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>
<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.
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.
1 That's the program that takes the GuideML and outputs HTML in different skins and potentially for different platforms. You don't need to know this, but it might impress any friends you have who are techies.
2 Your page will not display at all and an XML error message will be shown.
3 And the reason is that in XML, every tag has to be defined and listed in the DTD (short for Document Type Definition). The tags in this list are case sensitive, and we would have to list both upper and lower case tags in the DTD, if we allowed both
<P> for example. In that case, the system would have to work through a list twice as long as a list which only allowed
<P> tags, making the whole process slower. Or something like that. We chose uppercase tags because they stand out more than lowercase ones - which is handy when you're furrowing your brow, trying to figure out why there are error messages all over the place.
| ||Click here to be the first person to discuss this Guide Entry|
A5974374 (Help Page)
Written and Researched by: