New tricks for the word processor

Wikifying Writer

By Dmitri Popov

If you were to add wiki elements to OpenOffice.org Writer, which features would be useful and what benefits could they offer? According to Wikipedia, a wiki is "a website that allows visitors to add, remove, and edit content" or "a collaborative technology for organizing information on websites" [1]. The collaborative aspect of wiki is often considered its most important element, but what makes a wiki special is its ability to grow dynamically, usually implemented through the use of wiki words [2]. When you add a wiki word, the wiki automatically creates a link, generates a new page, and adds it to its index. This surprisingly simple technique allows users to "grow" the wiki on the fly and moves the burden of managing content and structure from the user to the system itself, which is something you can use not only for publishing content on the web, but also when you work with text documents.

To better understand how this might work, I'll take a look at a concrete example. Let's say you are working on a research paper about bird migration. When writing about Turdus merula (blackbird), you might want to create a new, separate document describing the bird's characteristics.

Also, you might want to link the first occurrence of the word blackbird to the respective Wikipedia article.

Finally, to keep tabs on all the documents and navigate through them, you might want to generate a separate file containing a list of all documents related to your research paper. Ideally, you would appreciate the ability to convert all the documents into HTML pages or Word files.

What Is QuasiWiki?

Although you can do all that using Writer's tools, it would require so much manual work that it wouldn't really be worth the trouble. However, the QuasiWiki extension [3] lets you add features that mimic wiki behavior, so you can create, link, and manage documents as well as link words to Wikipedia with just a few clicks. Basically, QuasiWiki allows you to treat Writer documents as wiki pages and directories as wikis. The extension itself consists of several macros (Figure 1) that perform different tasks. Here is a list of QuasiWiki's macros and their brief description:

• New Wiki: The macro creates a directory (wiki) for storing related Writer documents (wiki pages). In the bird migration example, this would include the main document and linked files. The macro creates a new directory and a blank document in a location specified by the user.

• Wikify Word: The macro links the selected word in the current document to the new page. For example, if the word blackbird is selected, the macro automatically links it to the created blackbird.odt document.

• Create Index: The macro scans the specified directory and generates a new document containing a hyperlinked list of all documents.

• Link to Wikipedia: The macro links the currently selected word to the related article in Wikipedia.

• Convert to HTML and Convert to Word: The macros convert documents in the specified directory into HTML-formatted pages or Word documents.

Figure 1: QuasiWiki is an extension that adds a few wiki-like features to OpenOffice.org Writer.

Anatomy of QuasiWiki

To better understand what makes QuasiWiki tick, I'll take a look at the key macros that provide the extension's core functionality. The Wikify Word macro allows you to turn any word in the document into a wiki word. When you select any word or text segment in the document (e.g., "LoremIpsum") and run the macro, it creates a document called LoremIpsum.odt in the same folder as the current document and then links the selected word to the created file. To see how the macro does this, I'll dissect it.

The macro starts with defining variables and initializes the currently opened document:

Sub WikifyWord()
Dim ThisDoc As Object, WikiWord As Object, WikiWordURL As String
Dim DocURL As String, DocDir As String
Dim Args1()
Dim Args2(0) As New com.sun.star.beans.PropertyValue
ThisDoc=ThisComponent

Next, the macro has to obtain the path of the currently opened document. The standard library in OpenOffice.org already contains a routine that can obtain the path of the open document, and the macro can make use of the routine by calling the Tools library first:

If (Not GlobalScope.BasicLibraries.isLibraryLoaded("Tools")) Then
   GlobalScope.BasicLibraries.LoadLibrary("Tools")
End If

To obtain the path of the current document, the document must be saved first. The macro runs a check to ensure that:

If ThisDoc.hasLocation=False Then
MsgBox "You must save the document first!" :End
End If

Now the macro can obtain the document's directory, which is pretty straightforward with the DirectoryNameoutofPath() routine:

DocURL=ThisDoc.getURL()
DocDir=DirectoryNameoutofPath(DocURL, "/")

The macro checks to see whether the user has selected a word or a text segment and then constructs a full path to the new document named as the currently selected string plus the .odt file extension:

WikiWord=ThisDoc.CurrentController.getViewCursor
If WikiWord.String="" Then
MsgBox "Please select a word or a text segment first!" :End
End If
WikiWordURL=DocDir & "/" & WikiWord.String & ".odt"
WikiWord.HyperlinkURL=WikiWordURL

To make the newly created wiki word stand out, the macro applies blue color and underlines the linked word:

WikiWord.CharColor=RGB(0,0,255)
WikiWord.CharUnderline=com.sun.star.awt.FontUnderline.SINGLE

Finally, the macro creates a new document with the specified name and in the specified location:

ThisDoc=StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Args1())
ThisDoc=thisComponent
Args2(0).Name = "Overwrite"
Args2(0).Value = True
ThisDoc.storeToURL(WikiWordURL, Args2())
End Sub

The Create Index macro is another essential component that allows you to generate quickly a hyperlinked list of the documents in a specified directory.

The way the macro works is rather simple - the macro asks the user to enter the path to the directory containing Writer documents, then it creates a blank .odt file and populates the file with the hyperlinked file names of the found documents. See Listing 1 for the full code of the macro.

Knowing how both Wikify Word and Create Index macros work, you can tweak them and extend their functionality. For example, you can combine the Wikify Word and Create Index macros so that every newly created document will contain links to the existing files.

01 Dim SourceDir as String, File As String
02 Dim ThisDoc As Object, Cursor As Object, DocText As Object
03 Dim Args()
04 SourceDir=InputBox("Source directory")
05 File=Dir(SourceDir & "*", 0)
06 ThisDoc=StarDesktop.loadComponentFromURL("private:factory/swriter", "_blank", 0, Args())
07 DocText=ThisDoc.Text
08 Cursor=DocText.createTextCursor
09 Cursor.paraStyleName="Heading 1"
10 DocText.insertString(Cursor, "QuasiWiki sitemap"+Chr(13)+Chr(13), false)
11 Do While Len(File)>0
12 Cursor.HyperlinkURL=ConvertToURL(SourceDir & File)
13 DocText.insertString(Cursor, File+Chr(13), false)
14 File=Dir
15 Loop
16 End Sub

Using QuasiWiki

Although understanding how QuasiWiki works and tweaking it requires a working knowledge of OpenOffice.org Basic, the extension itself is easy to use. If you don't feel like fiddling with the macros, you can simply install the QuasiWiki extension and start using the new features right away.

Installation

To install QuasiWiki, download the latest release from its website. In OpenOffice.org, choose Tools | Extension Manager and select My Extensions.

Press the Add button, select the downloaded extension and press OK. Once the extension is installed, restart OpenOffice.org. To create a new wiki, choose QuasiWiki | New Wiki.

Use the New Wiki dialog window to specify the path to the new wiki, its name, and the name of the initial document (Figure 2).

Figure 2: Creating a new "wiki" with QuasiWiki is as easy as specifying a few parameters.

To create a wiki word, select the word you want to wikify and choose QuasiWiki | Wikify Word. To quickly locate a document in the wiki or to view a list of all the documents, you can use the Create Index command.

The command creates a hyperlinked list of all the files in a specified wiki, and you can open the document you need by simply clicking on its name.

Publishing Your "Wikis"

The Convert to HTML feature allows you to convert all the documents in a particular wiki into HTML pages at one time.

Because the HTML export engine in Writer is far from perfect, the Convert to HTML feature is only good for a quick-and-dirty way of publishing your documents online. However, there are other ways to publish your documents on the web. If you are using DokuWiki [4], you can install the DokuWiki extension [5] that is based on the DokuWiki macro [6]. This extension converts the currently opened Writer document into a DokuWiki-formatted page. This extension will eventually be included in the QuasiWiki project.

Final Word

Although QuasiWiki doesn't magically transform OpenOffice.org into a wiki system, it adds a few features that can help you use the conventional word processor in a completely new way. And because the extension is released under GPL, you can tweak it to your heart's content. You can also submit bugs, questions, and feature requests on the project's SourceForge page [7].