Grotag User Guide

$Revision: 219 $

Table of Contents

1. Installation
Mac OS X
Other platforms
2. The user interface
Launch Grotag
Open an Amigaguide document
Browse a document
Export a document to a different format
3. Command line usage
Launch Grotag
Show help and other information
Validate Amigaguide documents
Pretty print and fix Amigaguide documents
Convert Amigaguide documents to HTML
Convert Amigaguide documents to DocBook XML
4. Acknowledgment
5. Changes
Version 0.2.0, 04-Jan-2012
Version 0.1.1, 05-Oct-2008
Version 0.1.0, 19-Sep-2008

List of Tables

2.1. Browsing a document

Grotag views Amigaguide documents or converts them to HTML and DocBook XML. Additionally it can validate and pretty print such documents.

Amigaguide is a file format and application for AmigaOS[1]. It enables to author and view hypertext documentation to some extend comparable to HTML or WinHelp. Most of the online documentation written for Amiga applications or about developing Amiga applications uses Amigaguide. Outside of AmigaOS however Amigaguide is unused and consequently hardly any viewers exist.

Altough most Amigaguide documents are not particular useful without access to an Amiga (real or emulated), occasionally a need arises to read such documentation on other platforms. Grotag is designed to address this need. It allows to convert Amigaguide documents to the platform independent HTML format, for which viewers exist on any reasonably modern system. Furthermore you can convert to DocBook, a format popular for technical documentations, allowing to bring along existing manuals into the 21st century for further editing.

Grotag is written in Java (version 1.5 or later), which is supported by many current platforms such as Mac OS X (version 10.5 or later), Windows and Linux to name just a few.

To find out what is new in this version, see the revision history. For updates and support, visit the Grotag homepage at

[1] The original Amigaguide is still available from any Aminet mirror, for example

For Mac OS X, visit and download Grotag-x.y-z.dmg, where x.y.z refers to the current version number. Double click the disk archive to mount its contents as new device and open it in the Finder. It contains an application named Grotag resp. Simply drag and drop this application in any folder you like to launch it from, for example /Applications or ~/Applications.

For other platforms, visit and download, where x.y.z refers to the current version number. After extracting the archive, you should see at least the following files:

  • Grotag.jar - The application Java archive.

  • license.txt - A text file describing your rights related to Grotag. In short: It is an Open Source application and you do not have to pay money for it.

Now simply move Grotag.jar to a folder from where you want to start it. Under Windows, this could be in C:\Programe Files, under Unix it might be /usr/local/bin or ~/bin.

To launch Grotag from most Desktop environtments, simply double click Grotag.jar. In case this does not work you have to use the command line as described in Chapter 3, Command line usage.

This chapter describes how to perform common tasks with Grotag using the graphical user interface. This provides a comfortable way to access most functions using the mouse and keyboard. For repetetive tasks and automatization a probaly better choice is described in Chapter 3, Command line usage.

Once the document has been opened, you can browse it. As Amigaguide is a hyper text format just like HTML, viewers for it are fairly similar to web browsers. A major difference however is that Amigaguide automatically relates previous and next pages, so it is easily possible to sequentially browse a document with a standardized user interface. Furthermore authors can specify special pages containing a table of contents, an index, or a help page.

Grotag offers several toolbar buttons and menu items to easily access all these pages, refer to Table 2.1, “Browsing a document” for details.

The following ressources have been helpful for developing Grotag:

  • MRJAdapter allows to integrate Java applications nicely into Mac OS X.

  • Crystal is the icon set use in the toolbar.

  • Salfara's website documents the Amigaguide format quite dilligently.

  • The agr command line Amigaguide reader includes a couple of interesting test documents.

This chapter describes improvements compared to earlier versions of Grotag.