GuideDog was a project started by Felonious Monk to attempt to provide one of the most requested features of h2g2: a WYSIWYG¹ editor. As you will know, h2g2 uses a code called GuideML (it's called a mark-up language) to format articles. WYSIWYG interfaces allow you to format things exactly as you would in a word-processor, and the code is generated behind the scenes.

The GuideDog program made great progress, but programming difficulties arose, prompting a need for a new approach. This new project, GuideDog for OpenOffice, is a novel way to achieve the same goal of an h2g2 WYSIWYG, its main advantage being compatibility with just about every computer system out there. It is a new approach because it is effectively a plug-in for an existing word-processor: OpenOffice.org Writer.

More detailed information about all this is given below, but you don't have to read it. It might be a good idea to read it if you aren't familiar with the more technical stuff.

To get started, follow these instructions:

1. Download and install OpenOffice. Your computer is bound to be fit to run it.

2. Download GuideDog for OpenOffice.

3. Unzip the archive.

4. Launch OpenOffice, and if it hasn't already done it, open a new text document.

5. Click on the 'Tools' menu, and then click on 'XML Filter Settings...'

6. Click the 'Open Package...' button.

7. Browse to where you downloaded GuideDog for OpenOffice and select the file called 'GuideDog.jar'.

8. Click the 'Close' button.

How to write an Entry

1. Start OpenOffice and go to the 'File' menu. Hover over 'New', and then click 'Templates and Documents'.

2. Double-click the folder called 'GuideDog'.

3. There should be one file in here. Double-click it.

4. To the box that appears, say 'Enable macros'. If you have nightmares about enabling macros², read the section called 'Macro-free Template'.

5. Replace the word 'Title' with the title of your Entry.

6. Read the rest of the details in this section and write your Entry. When you are done, you must save your document in the default format.

At this stage, GuideDog for OpenOffice is not finished. You may find a few bugs. Notably, it doesn't fully support tables and you'll come a cropper if you try to nest lists inside each other. Other than that, the main features are there: bold, italic, subscript, superscript, lists, headings and subheadings, hyperlinks and footnotes. To write your Entry... just write your Entry! Do it exactly how you would normally word-process a document... but remember these few points:

• To insert a heading, press the 'Header' button on the toolbar (it looks like the Brunel toolbar's button). You can do this before you write the heading's name or afterwards by selecting the text you want to make a heading.

• Likewise, use the 'Subheader' button to insert a subheading.

• Insert footnotes by going to Insert > Footnote. Then press OK.

• Insert hyperlinks by clicking the 'Hyperlink' button (right of the Redo button), or going to Insert > Hyperlink. If you have selected text, then that text will be made a link to the address you type (or paste) into the 'Target' box. If you are linking to an h2g2 Entry, browse to the Entry in your browser and paste in the full address of it³.

• The style of the document will roughly match h2g2's Brunel style.

• Have fun, and please report any bugs, findings, comments, complaints, suggestions or questions to Baryonic Being, either at my personal space, or by e-mailing me at the address given on the GuideDog for OpenOffice project website. I'm 'fermion'.

How to put your Entry on h2g2

You should have saved your Entry in the default format (OpenDocument). To get it on h2g2, you need to save it as GuideML. To do this, go to File > Save As. There's a drop-down menu where it says 'File type'. Near the bottom of the list you will see 'GuideML'. Select this and save your document somewhere easily accessible. To avoid any mistakes at this stage, it's a good idea to close your document completely.

Now, open the GuideML file in a text editor. For Windows users, this probably means opening Notepad and then opening the file from there (you will need to opt to see 'all files' before you will find it). Select all of its contents and copy it to the clipboard (by pressing Ctrl+C).

Go to h2g2 and add a new entry. Paste all the stuff into the box, click the radio button marked 'GuideML' and press 'Change style'.

Tada!

When you need to edit/update the Entry, open the OpenDocument file (which has the extension ODT). Do not open the GuideML file. You can save over the GuideML file when you next need to copy the GuideML onto h2g2.

You may have noticed a menu item called 'GuideML'. Ignore this for now. In future, it will have a function that copies the GuideML to the clipboard automatically! Well, I hope it will.

Macro-Free Version

Macros can contain viruses. The macros included in this program are almost certainly safe, but if you're worried, or if you can't be bothered to click the 'Enable macros' button all the time, you can use a macro-free version of the import template. To do this, go to Tools > XML Filter Settings. Select the GuideDog entry and press the Edit button. Click the 'Transformation' tab then press the Browse button next to the 'Template for import' field. Browse to where you downloaded GuideDog for OpenOffice, and select the file called 'Brunel.ott' in the gd4oo directory.

If you have decided to read the more detailed information below, keep in mind that this Entry itself was created mostly with GuideDog for OpenOffice!

About OpenOffice

OpenOffice.org is a free, open source office suite developed by a community of programmers worldwide, and supported by Sun Microsystems, who make a commercial version of it called StarOffice. It is the most major competitor to Microsoft Office. The fact that it's free of charge gives it a strong advantage from the off.

It supports all of Microsoft Office's major file formats⁴ and includes programs for word-processing, spreadsheets, presentations, drawing and databases and most importantly, it can edit XML formats.

About XML

XML stands for eXtensible Mark-up Language. It's an umbrella term for languages that use the hierarchical 'tag' structure. XHTML is the most famous example, being the standard language for web pages. Just go to View > Source on this page to see some HTML.

GuideML, the format for Guide Entries like this one, is also an XML dialect. It shares some common features with HTML. To see the GuideML of this page, replace the letter 'A' in the URL in the address bar with the word 'test', and navigate to that page. This works with any Guide Entry.

The World-Wide Web Consortium (W3C), amongst others, believe that XML will take over the world of data interchange, because it's very good at storing data, while simultaneously storing information about what that data means. It's also easy to extract data from XML files, and even transform it into other XML languages so that it can be used in other contexts. RSS feeds, those neat little things that allow you to keep up with the news as it's updated, and podcasts, which are a kind of Internet radio programme, are also XML files. Sometimes it's nice to transform RSS feeds into web pages. For this sort of thing, W3C created XSL.

About XSL

XSL is the eXtensible Styling Language. Its main component, called XSLT (where the 'T' means Transformations), specifies how one XML file should be transformed into another. XSL is also an XML dialect, but it's the one that most resembles a programming language. We won't go too in depth about XSL here; that's all we really need to know.

So what's all that got to do with GuideDog?

Well, as we have seen, Guide Entries are written in an XML format. What we haven't seen yet is that OpenOffice documents are also written in an XML format. (Penny drops) That means that XSLT can be used to transform an OpenOffice file (one XML format) into GuideML (another XML format), giving you the full comforts of a modern word-processor, and the output that can get your work in the Guide.

OpenOffice stores its documents in the OASIS OpenDocument file format. Don't worry if all this sounds too complicated - they're just names. We're only concerned with the word-processing aspect here. If you use Microsoft Word, you're probably used to saving your word-processed files as Word documents (with the extension of .doc). In OpenOffice, they're saved (by default) as OpenDocument text files (with the extension of .odt). ODT files are actually an archive of lots of XML files. And that's what makes them easy to manipulate for our purpose here.

OpenOffice has a built-in feature for importing and exporting different varieties of XML formats. The system is called an XSLT filter. What it comes down to, is that you can open a GuideML file just like any other word document, edit it, and then save it as another document while you edit it. And you can start a new document from scratch, knowing that when you save it, you will have the option of saving it as 'GuideML'. Pretty good, isn't it?

The GuideDog XSLT filter consists of three files:

• An XSLT file to transform GuideML into OpenDocument.

• An XSLT file to transform OpenDocument into GuideML.

• An OpenOffice template file that defines the styles of the document.

You can find these files in the 'src' directory of the downloaded GuideDog package. These same files are bundled up in the binary 'jar' file.

Stay tuned for future developments.

If you want to help

If you have experience in XML, XSLT and OpenDocument, or don't mind learning it, feel free to contact me and you can help with the development.

This is a FLOSS project - that means Free/Libre Open Source Software. It is being hosted on a Sourceforge project page.

Of course, anyone can test the program, and if you do, I encourage you to tell me what happens, report any bugs, and say how you think it could be improved.

Getting Entries In

To get the GuideML of any Entry, go to the URL of the page in your address bar, and replace the letter 'A' with the word 'test'. Navigate to that page and you'll see the source GuideML in a text box. If it's a personal space page, replace the 'U' with 'TestUserPage' instead.

Getting Entries Out

At the moment, the method described in the instructions at the beginning is probably best, until the copy GuideML to clipboard function has been implemented. Until then, you can attempt to automate the procedure by using a scripting language. Under Windows, this might be possible with VBScript, which is very easy to learn. Under Linux, you might try a program called 'xclip'. You can then use the command 'cat GuideEntry.gml | xclip' to add the contents of that file to the clipboard. Middle-click to paste it. Under Mac OS X, you don't need to download any new software; you can use the 'pbcopy' command in place of 'xclip', or if you have Tiger, you can use Automator to make a little application. If there is any demand for this, post a conversation below and I'll give further instructions.

Status

The table below gives the status of tags in approved GuideML only. I'll get on to non-approved GuideML when this table has DONEs all over it.