$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
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 http://grotag.sourceforge.net.
[1] The original Amigaguide is still available from any Aminet mirror, for example http://aminet.net/text/hyper/aguide34.lha.
Table of Contents
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.
Table of Contents
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 → . In the resulting dialog select the file and click the 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
| Task | Toolbar icon | Menu entry | Related 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. |   | → , → | @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. |  | → | @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. |  | → | @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 → . 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.
Table of Contents
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.
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.
Fixed launching under Mac OS X 10.6, which could not execute the included PPC Java launcher.
Added menu item → to export the document currently viewing to other formats.
Added GUI settings to be preserved using the Java Preferences API.
Fixed button, which seemingly navigated to random pages.
Changed toolbar buttons to use icons instead of text lables.
Added button.
Added proper About dialog.