Publishing with OOo Writer and DokuWiki

OpenOffice.org Writer offers a wide range of sophisticated tools for creating complex documents such as manuals and technical documentation. However, when it comes to publishing the finished results online, your options are rather limited. You can, of course, use OOo Web to convert existing files into HTML, but you might want a more powerful and flexible tool to maintain the published documents online — a wiki, for example, and specifically DokuWiki, which is designed for documentation.

A wiki, in its simplest form, is software that allows anyone to edit any Web page published on a given site. You can log in (if the wiki supports user authorisation), add new pages, and edit existing ones. Since most wikis include version control tools, they are particularly suitable for collaborative editing. Using a wiki, you can keep track of all changes in a Web page and compare different versions of a page side-by-side.

DokuWiki is a wiki designed especially for managing documentation. Apart from the nice lightweight user interface, DokuWiki’s includes useful features such as newsfeeds, support for multiple languages, and section editing. More importantly, since DokuWiki keeps all the data in text files, it doesn’t rely on MySQL, which greatly simplifies the installation procedure and maintenance.

To install DokuWiki, unpack the downloaded DokuWiki file, copy the resulting DokuWiki folder onto your Web server, and make the data directories (data, attic, and media), the logfile (changes.log) and the user file (conf/users.auth) writable by the server. (See the application’s installation instructions
for more details.)

By default anyone can edit any page on your DokuWiki site. However, when you are dealing with documentation, you might want to limit access to authorised users only. Here is how to quickly protect DokuWiki. Edit the conf/dokuwiki.php file and scroll down to the Authentication options section. Set the $conf['useacl'] option to 1 and $conf['openregister'] to 0. The latter option disables user registration, so you next have to add users manually to the conf/users.auth file.

The first line of users.auth shows how the user information should be formatted. Here’s an example:

davidsmith:dae10f355c290d2c6f12205227801ed0:David Smith:davidsmith@mail.com:admin

Note that the password has to be MD5-encrypted. To encrypt the password, you can either use a
simple PHP script or visit one of many Web sites that can do it for you.

Finally, you have to edit the acl.auth file as follows:

*    @admin    255

*    @ALL        1

This allows all users in the admin group to create, edit, and delete pages, and everyone else to view pages only. Check the documentation if you need to fine-tune the privileges.

Once DokuWiki is installed, it’s time to configure OpenOffice.org Writer. To be able to use Writer with DokuWiki, you need to download and install the Iannz DokuWiki macro, which parses the currently opened Writer document, converts it into the DokuWiki format (the original document remains intact), and copies it into the Clipboard. All you have to do then is paste the contents of the Clipboard into a new DokuWiki page.

To install the macro go to Tools > Macros > Macro… > Organizer > Libraries. Make sure that soffice is selected in the Application/Document drop-down menu. Click Append…, point to the DokuWiki macro file, and click Open. Untick the Standard check box, but make sure DokuWiki is ticked. If you are updating from an older version, check Replace existing libraries. Finally, press the Close button.

To make it easier to access and use the macro, you might want to add it as a menu item. To do that, go to Tools > Configure… > Menu. Select the desired location in the top list box (~Copy, for example). In the Category list box click the plus-sign next to OpenOffice.org BASIC Macros and the plus-sign next to DokuWiki, then click modDokuWiki. From the Function list, select DokuWiki. Finally, click the New button and press OK. After that’s done you can run the macro by choosing the DokuWiki item from the Edit menu.

Before you convert Writer files into DokuWiki, make sure you read the compatibility notes in the macro document. You should also keep in mind that the macro can correctly process images only when they are anchored as character. All images will be converted into the DokuWiki format as {{wiki:PictureName.png}}, where PictureName.png refers to the name of the picture as it appears in the Navigator. This means that before you can convert a Writer document containing graphics, you have to change the pictures’ names to the names of the corresponding files and upload the them into the media/wiki/ directory. To change the name of a picture in the document, open the Navigator, locate the picture in the Graphics section, right-click on it, and choose Graphics > Rename. The three-letter extension refers to the format the original picture file is stored in (for files stored in PNG format the extension is .png, for JPEG files the extension is .jpg, and so on). When the Writer document is ready, run the DokuWiki macro and paste the contents of the Clipboard into a new DokuWiki page.

Dmitri Popov is a freelance contributor and an avid OpenOffice.org user. His articles have appeared in
Russian, British, and Danish computer magazines.