1. Introduction to AmigaGuide

AmigaGuide format is, for all those who didn't have just heard something about it, a very old format, delivered with the earliest version of AmigaOS (as far I know, the v1.3 dated from 1985!) and looks like very closer to a subset of HTML.

AmigaGuide split the file into "nodes", and only one node at a time can be displayed. Moreover, it exists special AmigaGuide commands (similar to HTML anchor tags) that can link nodes together.

The purpose of a such format is to display only relevant part of file, do not reveal the thousands lines that most documents are composed of. That's very important because most of time, we are just interrested by a very small part of the file, and because it's necessary to find quickly the desired piece of information, that AmigaGuide offers the possibility to structure very efficiently the content of the file.

It's very closer to HTML format, except that more than one page can be "packed" into a single AmigaGuide document. This isn't a worse idea, since it greatly simplifies documentation management.

By the time, AmigaGuide has evolved, and is now composed of a subsequent set of commands, that can produce nice and user-friendly documentations, and because I found nothing on Unix that can replace efficiently this format, I decide to write such program.

2. What you need before

This tool uses ANSI extensions of standard text to produce some nice colored text from AmigaGuide format. Therefore the only thing require to have, is of course a good, capable terminal interpreter. I use mainly rxvt for my test, althrough it works well will Konsole from KDE2, Linux console, xterm, and co.

Sadly it does not include AmigaOS terminal, although they are fully functionnal for graphics rendition, but differs notably in keyboard management, enough to be incompatible. Anyway, there exists a lot of better tool for this system (although not free software!).

AGR has been designed to be just a quick and efficient replacement for all those who want to quickly read AmigaGuide documents into their Unix terminal session. I think, I almost reach my goal.

3. How to use the program

The usage of this tool is dramatically simple. It accept only one argument on its command line, the file name you want to see.

Then, if file format is recognize, you will see the entry point of all AmigaGuide document, the "MAIN" node. You can of course scroll the page using cursor keys. Along the page you may notice special word colored in blue and probably underlined: this represents AmigaGuide nodes. By selecting such node, using Space key or enter, it is possible to "jump" to this node and see its content. To do this just highlight the desired node, using TAB key (forward highlighting), A or P keys (backward highlighting). At last, it is possible to get to the previous visited page, with the BackSpace key.

That's a classical sample session. Actually a lot of more commands are available. Here is an exhaustive list, starting from most frequently used:

q or CTRL/C

This simply quits immediatly the program, without any prompt.

cursor

Cursor keys are used to scroll vertically the document (up/down keys) or horizontally, in case of viewing a wide document.

i, j, k, l

These keys emulate the directionnal pad. Useful when the latter doesn't work.

PgUp, PgDown

Simply scroll up/down one page. The number of lines scrolled is of course dependant to the terminal window's height.

Home, End

Go to beginning/end of the displayed node. One more time, the emergency replacement keys are respectively `g' and `G'.

TAB, a

Two very useful shortcuts designed to highlight links of AmigaGuide document. TAB key tries to highlight the first visible link, starting from the upper left corner of screen, or the next to the current highlighted link, if any. 'a' key does the reverse job: it highlights the first visible link, starting from bottom right corner or just the previous link, if there was any highlighted before.

Space, Enter

As you've highlighted the desired node, you can entered in by using one of this keys.

Backspace

Return back to the previously visited node.

F1

Any AmigaGuide node can defined a special help node, reachable using this key.

F2

In the same way, it is possible to defined a link to an Index node. This key simply jump to this one, if it is defined.

F3

Similarly, a "Table Of Content" node can be defined, this key can search for it.

n, b

Nodes of an AmigaGuide document are placed one after the others. You can jump to the surrounding nodes of the one you are currently viewing, by using `n' to go to the next and `b' to go to the previous one. Be aware that document can redefines the order of where the nodes are placed.

+, -

Well, actually this tool is able to display other source, than AmigaGuide document (ie: standard text). This format can't contains tabstop information, giving to the viewed document a very ugly aspect if tabstop isn't set to 8. With this keys, you can adjust current tabstop number for this file and thus see it more corectly.

t

Tabstop is normally displayed in the status bar, everytime you change it. You can redisplay it, using this key without changing it.

r

If a background process has trashed your display, just use this key to refresh the screen. Sometimes, it's possible that terminal doesn't understand very well scrolling command, and just redraw the new appeared lines. With this command you can be sure that the whole screen will be redrawn, with no special hacks to optimize rendering.

?

AmigaGuide document holds several hidden properties, that aren't generally displayed by most AmigaGuide readers. I really don't know why, but as it is very simple to do, this tool can display them.

v

If a link can't be reached, an error will be displayed. But if you want to see the content that causes the error, use this key. Actually it exists other link type in AmigaGuide format, one can directly executes a system command. Because on Unix system it is particularly dangerous, that this link are represented using a different color and it is better to see the command string before to executes it.

=

This tool display in the bottom of the screen, the percentage of the file viewed. With this command, you can see the line number of the first line displayed among the total number of lines.

C

As this tool can read standard text format, with some ANSI colors specifiers, it is possible that this text file comes from AmigaOS environment. The problems with AmigaOS ANSI text, is that colors differ totally from Unix system, and so the resulting document will be rendered in a absolutly ugly way. This command will try to convert colors according to the standard colormap of Amiga Intuition v36+ (ie: OS2.0+). Sadly, only the 4 first colors are standardize, indeed I use the Iconographics style as it uses a similar colormap to the Unix one. Therefore colors order are:

	0:Light gray   1:Black  2:White   3:Light blue
	4:Yellow       5:Blue   6:Green   7:Red

4. Overview of supported features

Here will be describe the AmigaGuide format and the features supported by this tool. This is not a tutorial, although it's quite suffisant for understanding basic principles of AmigaGuide, which are actually not very complex. Anyway you can find good tutorials on any Aminet web site (http://us.aminet.net).

4.1 Background

Here will be described general priciples to know before reading more adcanced topics.

Basically, AmigaGuide documents are no more than standard text, in which a few set of commands enhance the formatting possibilities. Among, there are commands to turn on bold, italic or underlined styles, specify tabstop number, or change default color pen number, etc...

All AmigaGuide commands begin with the '@' symbol and are case-insensitive. Actually, there are 3 groups of comands: Global, Node and Attributes. Global commands are usualy specified at the begining of the document, before any nodes are defined, and apply to all the nodes in the document. Technicaly, they could be anywhere. Many commands can be used both globaly and inside a node.

Node commands are usable inside of a node (after a '@NODE' and before an '@ENDNODE'), and affect only the node in which they are used.

Attributes may be specified anywhere in a normal line. In addition to the '@' symbol, attributes always use a pair of braces ('{' and '}') to enclose the attribute name and possibly additional arguments.

Many commands have been introduced over time, so some commands require a minimum OS version. These commands may be used without too much worry about compatibility, since older versions of Amigaguide largely ignore unknown commands. In this document, unsupported commands will be marked by a special mention.

4.2 Global commands

The following commands must be used only once, at the beginning of the document and before any node definition, since no forward search will be done after the first encountered commands. The content of each of this commands will be accessible in the information window of agr.

This commands are case-insensitive, must be placed in the beginning of the line, and although it is not present, the '@' symbol must precede all of them.

DATABASE name

This is the most important command of an AmigaGuide document, since it identifies this file as an Amigaguide one. It must be placed in the very first line in the file, with no spaces before.

$VER: version string

Specify an Amiga standard version string. "VER" must be uppercase, although this tool doesn't take care, but AmigaDOS "version" command does.

(C) copyright

Specify a short copyright notice for this file.

AUTHOR name

Specify the author of this file.

MASTER path

Specifies the AmigaDOS file path of the original document this AmigaGuide file was derived from.

Here follows commands that can be placed both in global place or in a local node definition. In case of no local definition are provided, the global one will be used, and in no global exists, a default value is always available.

4.3 Hypertext path

Some commands (INDEX, HELP, NEXT, PREV, TOC,...) and the all purpose hypertext link can specify other nodes to jump to. They all support the naming of nodes within the current document, but they also all support a path along with that name which lets the node be located in any Amigaguide document.

4.4 Attribute commands

Attribute command must be placed in a node definition, otherwise it will be simply ignored. Remember that all commands must have the '@' symbol preceding. It isn't displayed for some strange compatibility reason, with previous version of AmigaGuide.

5. Features that will never work

Sadly there are thing that isn't and can't never be supported by this tool. Here is the description of standard problems that you may encountered.

First incompatibility: Amiga file path. Of course, they differ from Unix ones, although they are almost similar. However this tool assumes that all path that refers to an external file, is written using AmigaOS conventions. Therefore they are always converted to Unix specs. Here are the main differences:

• AmigaOS directories are separated by just one slash ('/').
• If path begins by a slash ('/') or preceding another slash, it refers to the parent directory, and is replaced by '../'.
• If path contains a volume specifier (a name followed by a ':'), it is simply discarded.
• If AmigaDOS volume name is empty, then it refers to the root of current partition, therefore / on unix system.

Example:
	AmigaGuide path:          Unix translation:
	:Images/ScreenShot.IFF    /Images/ScreenShot.IFF
	//doc.guide               ../../doc.guide
	IMG:Photo.jpg             Photo.jpg

Actually several attempts are done to locate external files pointed by AmigaGuide nodes:

1. First, agr tries to open the translated path from the working directory of the process. This is not very compliant with AmigaGuide, but can be sometimes helpful.
2. If this failed, it will try from the directory where the starting document remains. This is actually the only attempt of original AmigaGuide.
3. If this fails once again and the path contains a volume name, it will look from an environment variable, whose name is the same as the volume, with all letters in uppercase (whatever the case of the real volume name is) and without the ':'. If the variable exists, it will replace the volume name, by the Unix path contained in this variable, and then try to open the file.
4. Finally a last ressort is to defined the variable AGR_PATH to make it point to a default search directory, which will be added in case of all other attempts failed.
5. At last, if this fails too, an error will be displayed in the status bar, with the file name not located.

The second problem comes from AmigaOS case insensitive path. Unix path are case sensitive, and to be fully compatible with AmigaOS, it is required to rewrite accession method to all files. This is quite annoying to do, and sadly, hasn't be done. This tool simply assumes that the path is correctly spelled, using Unix conventions.

Third, it exists special link type (namely rx and rxs), that can execute ARexx script or string. As Rexx isn't integrated at all in most Unix system such type of link are simply displayed as unknown type link, and shown in a different color (usually red), displaying an error when attemping to execute them.

Fourth, Command string contains in the "System"-type link, isn't converted at all. First, standard Amiga commands differ totally from Unix ones. Second, path can't be translated, since it quite impossible to determine whether a substring represents or not a path. Therefore, I decide to let it like it is.

Fifth, external link to ANSI text file are supposed to recpect full ANSI specs, and therefore no color translation is done. However, you can try to convert them from standard Amiga NewLook style to ANSI one, by using the 'C' key.

Other minor incompatibilities, the backslash character ('\'). In version earlier to v40, this character is process like any other, but document that want to use '@' symbol may encounter some problems. V40 spec indicates that all characters following the backslash should be processed as a normal one. Actually, I use a compromise between this two versions: when the basckslash is followed by the '@' or the '\', then only the following character is processed. Indeed, any other character will force to print both the backslash and the next character.

6. Some notes about sources

This tool is free woftware. You can do want you want with it, as all related documents that come with. As always, no warranty is given, it is at your own risk that your computer may burn into flames, when attemping running this tool. However, it has proved to be quite stable on my system. Why not yours?

Part of the sources has been taken from less package of Mark Nudelman, but has been greatly cleared, to just contains what's required for an Unix system. Although agr's sources are a lot of more readable than less ones, I've designed this tool as fast as possible, because I really needed it.

This tool was written in ANSI C, with some gcc specific functions, and is composed of a little bit more than 2100 lines of code, totalizing almost 59Kb. This quite reasonable for a such program, although code could be more clear.

This tool can perfectly be compiled under any Unix system with GNU developpement tools (make and gcc). You just have to type `make' in the source directory, and a command named `agr' will be generated. Then copy it whereever you want. It has been successfully compiled under Linux and Solaris. Documentation is written using an XML source and formatted with one XSL stylesheet per output format (HTML and AmigaGuide). Therefore you will need an XSLT processor to regenerate the documentation. I used Sablotron from Ginger alliance.

What can become more interesting, its the possibility to change standard colors that is used to display special tokens in the document. Actually, standard colors has been choosen to best fit on white with black background terminal settings. Although it's quite usable with other configuration, some people may find them perfectible.

Colors definitions are gathered in a simple C header file: AGNodes.h. Just scroll down a little bit the file, and you will find all the #defines. They represent of course the ANSI colors used to render text. You can for example change the default background colors by setting DEF_BGPEN define to '4', and thus force the background to be always blue. This is of course not a good idea, since it may produces strange result on poor terminal capabilities, therefore the only acceptable colors that may be changed is the foreground ones.