Using Approved GuideML in Approved Entries
Created | Updated Dec 18, 2011
Welcome to our comprehensive guide to the GuideML we use in Approved Entries (known as 'Approved GuideML'). This document details which GuideML tags we allow into the Approved section of H2G2, and as such it doesn't mention all the tags supported in GuideML, but does cover the full range of tags we have approved for use in the Approved version of H2G2.
This Entry is mainly aimed at Sub-editors, who do the final editing on Entries before they are Approved... but if you want your entry to be recommended for Approval in the Peer Review system, you can improve your chances of success if you stick to the tags listed here, and use them in the ways shown.
Approved GuideML
The following tags (and their closing equivalents) are allowed in Edited Guide Entries, and no others. All tags should be in UPPERCASE. Here they are, split into logical groups; the tags themselves are described in alphabetical order in the body of this document.
You can find the syntax details for each tag from the GuideML Clinic. This document describes how to use them stylistically, rather than syntactically.
Basic Structure
Text Markup
Headings and Rules
Links
Lists
Tables
In-house Tags
You may also see the following tags included in Approved Entries, but they have to be put in by the in-house team, due to technical restrictions. As soon as it's possible, you'll be able to play with them too.
- <FORM> and associated tags
- <PICTURE>
Why Have Approved GuideML?
Why have we picked a specific subset of GuideML for the Edited Guide? Well, it's fine for Researchers to use all sorts of flashy and groovy markup tags on their pages, but we have picked a subset that allows us to maintain a grip on the quality in the Edited Guide. Flashing text might be great for fans of psychedelia, but not in the edited section of the Guide. Furthermore, some GuideML tags, like <BOX>, have been 'deprecated' from the Edited Guide, but are still supported by the system; we'll just remove them from entries as they go through the editing system.
So this document details how to use the tags that we will allow through our editing process. If you're a Sub-editor then this document shows which tags you can use in Edited Entries; and if you're looking to write entries for consideration in the Peer Review system, then stick to these tags and these tags only to improve your chances of having something accepted into the Edited Guide.
Some Style Tips
On a stylistic note, it's much easier if you spread your markup out - just as it is easier to read things that are broken up into paragraphs and not just bunched together in a lump. So spread your entries out and use lots of blank lines between sections - it won't affect how your page looks on site, but it will make it easier if you ever want to change it.
If you want to use a text editor on your computer to prepare your code, then use something that is text-only like Notepad or similar. Word processor programs such as Word can do unpleasant things to some of the codes.
One more thing: when you are putting in GuideML tags, it's tempting to think in terms of gorgeous graphical layouts, but there's no need to. The text might end up appearing in an unsophisticated browser or on the screen of a mobile phone, so don't get carried away with how things look. That doesn't mean that there aren't a few rules to follow... but thinking in terms of markup rather than layout is the best approach.
And so begins our thrilling peek into the world of Approved GuideML.
<B> Tag
In the same way that <I> tags make text italic, <B> tags make text bold.
<B> and </B> can be used around the introductory words of a paragraph to form a mini-heading for sections too short to merit their own header or subheader. In the entry on The Beatles each of the band members appears like this:
George Harrison - Was lead guitar player for the Fab Four, and was also an occasional song writer and lead vocalist.
Note that the mini-heading is followed by a hyphen.
Use <I> for emphasis, rather than <B>, as in:
In the sitcom One Foot in the Grave, the main character, Victor Meldrew, is known for his catchphrase, 'I don't believe it'.
As a rule, <B> is not used outside the above mini-heading system.
<BLOCKQUOTE> Tag
Blockquotes are used to indent text and are particularly useful for quoting chunks of text, poems, and song lyrics. Make sure the quote is italicised, to distinguish the passage from the surrounding text, and delete any extraneous inverted commas. We wouldn't want to overdo it, would we?
Close the italic tags, then follow the quote with a line break <BR/> and a hyphen and then name the person who said or wrote the quote. The title of the person can go on the next line if it is a particularly long one.
Thus:
<BLOCKQUOTE><I>All happy families resemble one another, but each unhappy family is unhappy in its own way. </I> <BR/>
- Leo Tolstoy <BR/>
Russian Novelist</BLOCKQUOTE>
Note that the <BLOCKQUOTE> tag puts in spaces above and below the text so there is no need to put in extra <P> tags; indeed, treat <BLOCKQUOTE> tags like specialised <P> tags.
<BR/> Tag
Almost as if to deny everything that's already been said about opening and closing GuideML tags, there is one exception - <BR/>. Rather than opening and closing line breaks with <BR> and </BR> (which is legal, just a waste of characters), the two are shortened to form the shortcut <BR/>. Note that the slash (/) is placed after the letters BR.
<BR/> tags behave as a forced line break which can be particularly handy when quoting poetry or song lyrics:
<BLOCKQUOTE><I>
O! know, sweet love, I always write of you, <BR/>
And you and love are still my argument; <BR/>
So all my best is dressing old words new, <BR/>
Spending again what is already spent <BR/>
</I></BLOCKQUOTE>
Or after a blockquote when crediting a quote, like this:
<BLOCKQUOTE><I>
Brevity is the sister of talent.</I><BR/>
Anton Chekhov</BLOCKQUOTE>
There's more about <BLOCKQUOTE> tags above.
<CODE> Tag
The <CODE> tag is used for quotes from programming languages, such as we have done throughout this entry when writing GuideML tags.
That's its only use, but it's an important one if you're writing a technical entry.
<FOOTNOTE> Tag
Here's when to use footnotes:
Traditionally footnotes are used to cite academic or literary references, or quotes such as in the entry on Idiot Sticks.
Footnotes are also useful to add in additional information, such as pronunciations or explanations of foreign terms (see footnote two in Syktyvkar, Komi Republic, Russia).
Footnotes are also used to great effect as witty asides (see Limericks, for example).
Footnotes go between <FOOTNOTE> and </FOOTNOTE> tags, and they should be complete sentences: in other words they must start with a capital letter and end with a full stop or ellipsis (ie three full-points in a row like this...). The position of the footnote is also important: insert it directly after the word you intend to add the footnote to, before any comma, full stop or parenthesis after that word. In other words this is correct:
Unless you've been dipped in lemon or lime juice1, you shouldn't use the word this way.
which is implemented with:
Unless you've been dipped in lemon or lime juice<FOOTNOTE>In which case you have bigger problems.</FOOTNOTE>, you shouldn't use the word this way.
The following, however, is wrong:
Unless you've been dipped in lemon or lime juice,2 you shouldn't use the word this way.
which would be (erroneously) implemented with:
Unless you've been dipped in lemon or lime juice,<FOOTNOTE>In which case you have bigger problems.</FOOTNOTE> you shouldn't use the word this way.
It's pretty easy to spot once you get used to looking at the punctuation in relation to the superscripted number.
For more information see the Sub-editor's Style Guide and the Edited Guide Entry on the subject of footnotes.
<HEADER> and <SUBHEADER> Tag
By using <HEADER> and <SUBHEADER> tags, headers and subheaders break up the text into convenient compartments. It's best to keep the text inside headers and subheaders as simple as possible, and take out any extra punctuation such as full-stops, exclamation marks, semicolons, and colons. Capitalise each of the major words in headers and subheaders, as in the following examples.
This is What a Header Looks Like
and it was created with the GuideML:
<HEADER>This is What a Header Looks Like</HEADER>
And This is What a Subheader Looks Like
created with:
<SUBHEADER>And This is What a Subheader Looks Like</SUBHEADER>
Don't start an Edited Entry with a header: having a preamble introduction is a nicer way to ease the reader into the topic. Then you can begin to use headers with gusto! If the entry is a particularly long one, and the information under the header needs to be divided again, you can use subheaders within headed sections; for a good example of how headers and subheaders are used together see The A Team.
<HR/> Tag
The <HR/> tag inserts a horizontal rule - and that's it. Simple! However, in the Edited Guide, horizontal rules should be used sparingly, and only between paragraphs, not inside them. Therefore the usage is like this:
<P>...</P>
<HR/>
<P>...</P>
This is as opposed to simply using <HR/> like <BR/>.
<I> Tag
<I> tags make text slant to the right. In traditional publishing the names of films, plays, books, newspapers, magazines, titles of albums and foreign phrases (but not the ones that have been around for ages and are almost in constant use - café is a good example of this) are all italicised. It's a convention that we're following in the Edited Guide - for more of this kind of stylistic information see our Style Guide for Sub-editors. Also, interestingly, names of ships should be written in italics.
To make a portion of text italic, simply enclose it with <I> and </I> tags, as in the <BR/> example above.
<LINK> Tag
A particularly nifty device, which we're rather fond of, is the ability to link text to either another h2g2 entry, or an external website. The <LINK> tag also allows us to link to Researchers' Personal Spaces, but as a rule this should not be done in Edited Entries - if you come across an example when you think a Researcher should be linked to, just ask us for comment; whereas Edited Entries will always be in the Guide and can be linked to, specific Researchers may not always be active.
For example, by surrounding the words 'Hole Punches' with the following GuideML tags:
<LINK H2G2="A250435">Hole Punches</LINK>
the words 'Hole Punches' are automatically highlighted and underlined. When researchers click on words formatted like this, they'll be transferred to a whole new entry. Which is nice.
Linking to h2g2 Entries
When linking from an entry you are approving to other h2g2 entries, there are a couple of points to bear in mind:
The entries linked to should also be in the Edited Guide.
They should be direct and relevant. For example, the word 'poetry' should link to Poetry, rather than Poetry Events and Gigs in Glasgow, which, though a laudable entry, does not define the word 'poetry'.
Linking to External Websites
Applying GuideML like this:
<LINK HREF="http://www.man.ac.uk/">Manchester University</LINK>
will enable you to link to external websites.
There are also a few considerations to take into account when linking from the entries you are working on to external websites:
They must exist, so check that the links work.
They must be good ones. Think about whether the site would pass the h2g2 submissions guidelines. If the site links to a Personal Space and all it has on it is 'Hi, this is Dave's space and I'm really into the Sealed Knot. Here's some pictures of me and my mates pretending to be Roundheads and Cavaliers and re-enacting the Battle of Nazeby', with accompanying said photos, it probably doesn't provide enough information about what the Sealed Knot is to be a useful link. However, if the site provides good quality extra information and is not commercial, then it is certainly worth leaving in. Purely commercial links are not permitted.
Linking to off-site pictures is not allowed, due to copyright issues that can arise from this.
<OL> and <LI> Tags
Not used as often as <UL>, use <OL> with sequential instructions, such as in the methods of recipes. See Haggis or Velveeta Cheese, where the numbered lists are produced with <OL> tags. To create an ordered list, follow exactly the same method as for using <UL>, but replace <UL> with <OL> and </UL> with </OL>.
<P> Tag
The <P> tag is GuideML's most basic unit. It 'makes' paragraphs by putting a space above and below the text. Begin every paragraph with a <P> and end every paragraph with a </P>.
You can also use the ALIGN attribute to align paragraphs to the right and in the centre, but this is unlikely to be useful except in specific circumstances. For example, you might want to centre the text on a gravestone, like this:
A.N.Other
1953-2000
He Rocked
He Dropped
Rest in Pieces
<PRE> Tag
Like <CODE>, the <PRE> tag won't be used too often, but is useful for reproducing a specific textual layout that the space-removing aspects of GuideML would ruin. Any ordinary keyboard actions such as carriage returns or spaces will be implemented, when a passage is enclosed by <PRE> tags. The kind of text that would benefit from <PRE> tags would be the sort that zigzags all over the page, or like this:
Shall I part my hair behind? Do I
dare to eat a peach?
I shall wear white flannel trousers,
and walk upon the beach.
- TS Eliot, 'The Love Song of J Alfred Prufrock'
As with <BLOCKQUOTE> tags, <PRE> tags should be used in the same way as <P> tags - if you need to create monospaced text inside a body of normal text, use <CODE>.
<REFERENCES> Tag
If, during the course of your research, you come across a really good, relevant external site or Edited Entry to include in the one you are working on, but can't find a suitable word to link it from, you can put the entry number or URL with link tags, between <REFERENCES> tags at the end of the entry, thus:
</BODY>
<REFERENCES>
<LINK H2G2="A260281">Preparing a Chicken</LINK>
</REFERENCES>
</GUIDE>
And, hey presto! The link appears under 'Related Entries' in the margin.
This can also be applied to external websites and is preferable to just having 'Links' sections at the bottom of the entry.
<SUP> and <SUB> Tags
By using the superscript tags <SUP> and </SUP> you'll end up with something looking like this 623, ie six to the power of 23.
Subscripts are also possible using <SUB> and </SUB> and should be used for chemical formulae, as in H2O.
Tables
Tables should be used when, er, you need to lay out content in a table format. Good examples are Handy Latin Phrases and Cockney Rhyming Slang, where the table makes it easier to see what's going on.
You can find out the syntax for the <TABLE> tag at the GuideML CLinic, but essentially you should ask yourself the following questions before inserting a table into an Edited Entry:
Is a table the best way to lay out the data?
Does a border help to make the table more readable?
Would lots of small tables work better than one huge one?
Will this look OK on reasonably-sized browser windows?
When used correctly, tables are excellent, but when they're not necessary, they really get in the way. If in doubt, ask.
<UL> and <LI> Tags
Using <UL>3 with <LI> tags enables us to lay out text in lists in an easy-to-read format. This facility is particularly useful for:
- Lists of self-contained sentences
- Lists of short, snappy items (like this one)
Using <LI> tags can be laid out in one of two ways...
The first type should have whole sentences or paragraphs as its items, with full stops at the end of each item in the list. The instructions in the entry Getting Lost on Your Way to Somewhere New, is laid out in this fashion. The way to insert line spaces is by using: <LI><P> and </P></LI> tags, around each list item, as was done in the entry Sleep Deprivation:
<UL>
<LI><P>The first thing you are most likely to notice, if you are sleep-deprived, is a drastic increase in the frequency of your yawns. </P></LI>
<LI><P>The second thing you may notice, is a severe decrease in proper brain function. </P></LI>
</UL>
Doing this will indent, separate with a line space and put a blob in front of each list item, like this:
The first thing you are most likely to notice, if you are sleep-deprived, is a drastic increase in the frequency of your yawns.
The second thing you may notice, is a severe decrease in proper brain function.
The second way to lay out lists is for short list items of just a few words. These should have a capital at the start of the list item, but no punctuation at all at the end. No gaps between lines are required, so use: <LI>...</LI>, as in:
<P>When camping you will need:</P>
<UL>
<LI>A sleeping bag</LI>
<LI>A camping stove</LI>
<LI>A tent</LI>
</UL>
which gives a list that looks like this:
- A sleeping bag
- A camping stove
- A tent
Recipes
When writing recipes we put the word 'Ingredients' in <SUBHEADER> tags and list the ingredients in an unordered list with no <P> tags and no full stops:
<SUBHEADER>Ingredients</SUBHEADER>
<UL>
<LI>Milk</LI>
<LI>Sugar</LI>
<LI>Eggs</LI></UL>
We also put the word 'Method' in <SUBHEADER> tags but then list the sequence of actions as an ordered list (numericals) with <P> tags and full stops:
<SUBHEADER>Method</SUBHEADER>
<OL>
<LI><P>Pour the milk.</P></LI>
<LI><P>Add the sugar.</P></LI>
<LI><P>Beat the eggs.</P></LI>
</OL>
Tags We Don't Use
In theory, the fewer rules there are about using GuideML, the simpler it will be to format text in the subbing process. So, to make life simpler and to give the Guide a consistent style, there are a number of tags we don't use in Edited Entries (though, as noted, it's fine for Researchers to use them on their own pages). More details can be found in the GuideML Clinic.
Additionally, remove all HTML tags that aren't mentioned above. That includes favourites like <FONT>, <HR> and so on. Currently they would probably work, but this is not guaranteed in the future.
Also, use <B> rather than <STRONG>, <I> rather than <EM>, and <LINK> rather than <A> for links. Also, use <I> or <B> rather than <U>, the underline tag, and instead of using <HR> use headers and subheaders.
However, do use HTML entities for unusual characters, such as é, other accents and things like the degree symbols. Thanks to beeline for his list of Special Character Codes.
If you ever come across any Java objects, JavaScript, or an HTML form, please remove them. We used to support Java and JavaScript, but we no longer do.
And bear in mind that these guidelines have taken some time to compile, so some early entries will break the rules. Eventually we'll get round to fixing them, but if you do spot anything that breaks these rules, just shout. (We will be leaving some entries in sections until a better solution is implemented, but anything else is fair game for finger-pointing.)
That's all folks!
