Grotag User Guide

Thomas Aglassinger

$Revision: 219 $

Copyright © 2008-2012 Thomas Aglassinger

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

Table of Contents

Introduction
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

Introduction

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 http://grotag.sourceforge.net.


[1] The original Amigaguide is still available from any Aminet mirror, for example http://aminet.net/text/hyper/aguide34.lha.

Chapter 1. Installation

Table of Contents

Mac OS X
Other platforms

For Mac OS X, visit http://grotag.sourceforge.net 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. Grotag.app. Simply drag and drop this application in any folder you like to launch it from, for example /Applications or ~/Applications.

For other platforms, visit http://grotag.sourceforge.net and download Grotag-x.y.zip, 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.

Chapter 2. The user interface

Table of Contents

Launch Grotag
Open an Amigaguide document
Browse a document
Export a document to a different format

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.

To launch Grotag under Mac OS X, simply double click the application icon or drop a *.guide file on it.

To launch Grotag on most other platforms, simply double click Grotag.jar on the desktop.

In case this does not work, open a terminal window (console) and enter:

java -jar .../path/to/Grotag.jar

Soon after that Grotag should present you an empty window.

In order to read an Amigaguide document, you have to open one using the menu entry File → Open. In the resulting dialog select the file and click the Open button. Grotag loads the document, including all linked documents. For complex guides (such as the Amiga ROM Kernel Reference Manuals) this may take a while. Watch the progress bar in the lower right corner of the window to estimate how long it still going to take.

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.

Table 2.1. Browsing a document

TaskToolbar iconMenu entryRelated Amigaguide command
Browse back and forward through pages previously viewed.
  
Browse through the pages in sequential order. In case these buttons are greyed out, you are already at the first or last page. In case both of these buttons are greyed out, the document has only one page.
Go → Next, Go → Previous@next, @previous
Go to the contents page for the current page. In case this button is greyed out, the author did not specify a contents page.
Go → Contents@contents
Go to the page the document initially opened with.
  
Show the index page of the current document. In case this button is greyed out, the author did not specify an index page.
Go → Index@index
Go to the help page for this particular guide. Unlike the Commodore Amigaguide application, Grotag does not provide a default help explaining the controlls. In case this button is greyed out, the author did not specify a help page.
 @help

In order to read a document without an Amigaguide reader, you can export it to HTML or XHTML by using the menu entry File → Export. After you choose a base folder for the converted documents, Grotag creates a folder with the same name as the Amigaguide document without the suffix ".guide".

Additionally you can export to DocBook, which is useful if you want to integrate the information stored in the Amigaguide in an existing DocBook documentation. Be aware though that the DocBook variant has all the formatting information removed.

Chapter 3. Command line usage

Table of Contents

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

To launch Grotag from the command line, open a terminal window (console) and enter:

java -jar .../path/to/Grotag.jar --help

Replace ".../path/to/" by the location of the folder you extracted Grotag.zip to and where Grotag.jar is located.

As a result, you should see a short decription of the options you can pass to Grotag. Don't worry about them now, all of them will be explained later in this chapter.

Because it is somewhat boring to type that much each time you want to launch Grotag, it is recommended to define a console alias. In bash, simply enter:

alias grotag="java -jar .../path/to/Grotag.jar"

After that, you can simply run

grotag --help

to get same result as before. To avoid having to retype the alias each time you open a new terminal, add it to the shell startup file (for example ~/.bashrc or ~/.profile depending on your platform.)

To read a short description of all options available for Grotag, run:

grotag --help

To learn which version of Grotag you are using, run:

grotag --version

To obtain information about Grotag's license, run:

grotag --license

To validate an Amigaguide document named some.guide, run:

grotag --validate some.guide

In case Grotag detects any inconsistencies, it will report what it would have done in order to fix them. This isn't necessarily what you would have done to fix them, but still shows exactly where something is wrong.

If you trust Grotag to do the right thing, you can let it fix the reported issues by using the command line option --pretty.

Amigaguide never came with an authoring tool or a formal specification of the format. Consequently many existing Amigaguide documents contain little inconsistencies the rather lenient Amigaguide application stilled displayed without any trouble.

Grotag takes a different approach: it points even tiny little errors, and makes an attempt to fix it in a way that preserves the content while resulting in an documents that does not have the issue anymore.

Furthermore Grotag cleans up formatting and upper/lower case in mark up.

Warning

Note that the original version of the Amigaguide document will be overwritten and consequently be lost unless you made a backup copy of it before applying --pretty.

In order to clean up the file ugly.guide, run:

grotag --pretty ugly.guide

In case you want to clean up multiple files, you can pass all of them along at once.

To convert an Amigaguide document named some.guide to a set of HTML documents, run:

grotag --html some.guide

This creates a folder some in the current folder, which contains a *.html file for each node. The file for the main node is always called index.html.

To store the output in a different folder, specify it as a second option. For example, to store the HTML version of some.guide in ~/guides, run:

grotag --docbook some.guide ~/guides

To start reading, open ~/guides/some/index.html.

To convert an Amigaguide document named some.guide to a DocBook XML file named some.xml, run:

grotag --docbook some.guide

To use a different name for the output file, specify a second file. For example, to store the DocBook version of some.guide in other.xml, run:

grotag --docbook some.guide other.xml

The DocBook output does not preserve any formatting command like @{b}, @{fg shine} and so in. It only reproduces the structure of the document. Each guide represents a chapter, and each node is a section. If the Amigaguide document specified in the command line links to other documents, they will be included in the DocBook output as additional chapters.

Chapter 4. Acknowledgment

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.

Chapter 5. Changes

Table of Contents

Version 0.2.0, 04-Jan-2012
Version 0.1.1, 05-Oct-2008
Version 0.1.0, 19-Sep-2008

This chapter describes improvements compared to earlier versions of Grotag.