AmigaGuide

AmigaGuide is a mark-up language for hypertext documents, introduced by Commodore International in 1992 as part of Workbench 2.1 and later extended in Workbench 3.0 and 3.1. This article describes the AmigaGuide format and provides a complete list of its commands.

Comparing AmigaGuide and HTML

AmigaGuide and HTML were both developed in the early 1990s, but have different goals and take different approaches to representing hypertext.

Linking

HTML was designed to be used on the internet. Each HTML document is located at a specific URL and usually represents a single page (although JavaScript now allows entire applications to be created within HTML files). An HTML hyperlink points to a URL, which may end with a fragment (a string starting with #) to target a named location within the target document; that target may consist only of a fragment to link within the current document. Related documents can be specified using the rel attribute of links, but this information is usually not exposed.

AmigaGuide was designed to be used on the local filesystem. Each AmigaGuide file consists of one or more nodes, which represent the pages within the file. An AmigaGuide hyperlink points to a file, and may specify a node and optionally a line number within the target file if it is an AmigaGuide document; the file name may be omitted to link to a node within the current file. Nodes can specify previous, next, content, index, and help nodes, and these can be accessed through a toolbar displayed at the top of the window.

Mark-up

HTML documents are marked up using tags consisting of an element name contained within angle brackets (< and >), with closing tags having / before the element name. Attributes for an element may be specified within the opening tag. The document represents a tree structure, so tags must be correctly nested: <b><i>text</i></b> represents text within an i element within a b element, whereas <b>text</i> is not valid HTML. Consecutive whitespace characters within an HTML document are usually collapsed to a single space, but finer control of whitespace handling is possible.

AmigaGuide documents are marked up using commands consisting of a command name preceded by an at-sign (@). Some commands occur on their own line, and may have options specified after the command name. Other commands occur within text, have the command name contained within braces ({ and }), and may have options specified within the braces. Formatting commands exist in pairs to turn on and off formatting, but do not need to be correctly nested: @{b}text@{ui} is valid, with the @{ui} command having no effect if italic text has not already been turned on. Whitespace within nodes is preserved by default, but later versions of AmigaGuide introduced commands to change this behaviour.

Scripting

HTML documents can use JavaScript to add interactive functionality. JavaScript is executed in a sandbox: it can modify the current document but is isolated from other documents and the rest of the operating system.

AmigaGuide documents can contain commands to execute AmigaDOS commands and ARexx scripts. AmigaDOS commands and ARexx scripts have full access to the operating system and may carry out malicious actions.

Version history

The AmigaGuide format and a viewing application with the same name were introduced as part of Workbench 2.1. The AmigaGuide application could only display AmigaGuide files and plain text files, so hyperlinks were limited to documents in these two formats. The major structural commands were present in this original release, but formatting commands were limited to changing the font and selecting from a limited range of foreground and background colours.

Workbench 3.0 introduced the datatypes system and the associated viewing application Multiview, which can display any file for which a datatype has been installed. The standard datatypes include AmigaGuide and various image formats, giving AmigaGuide documents the ability to hyperlink to other file types. The AmigaGuide datatype introduced several new commands, including formatting commands for bold, italic, and underlined text.

Workbench 3.1 introduced further new AmigaGuide commands, including event handlers allowing ARexx scripts to be executed when nodes are opened or closed, and commands for more advanced handling of whitespace.

The structure of an AmigaGuide document

An AmigaGuide document is a text file marked up using commands consisting of a command name preceded by an at-sign (@). To include a literal at-sign it must be escaped with a backslash (\@), and as a result a literal backslash must also be escaped (\\). There are three type of command:

Global commands
Global commands occur outside of any node, and are used to define nodes and specify global metadata and formatting
Node commands
Node commands occur inside a node, and are used to specify node metadata and formatting
Text commands
Text commands occur within text, and are used to specify text formatting and to create hyperlinks and buttons

Global and node commands appear on their own line, and may have options specified after the command name. Text commands have the command name contained within braces ({ and }), and may have options specified within the braces. Options containing spaces must be written in quotation marks ("), except for global and node commands that have only one option.

Every AmigaGuide document starts with the global database command, which must occur on the first line and allows MultiView to identify the file as an AmigaGuide document:

1
@database

Nodes

Nodes are defined using the global node command, which has two options specifying a node name (used to link to the node) and node title (shown in the window title bar). All text and commands until the following endnode command are part of the node. For example:

1
2
3
4
5
6
7
@node node1 "First node"
This text is in the first node.
@endnode

@node node2 "Second node"
This text is in the second node.
@endnode

When the file is loaded, the first node in the document is displayed. The example above does not include navigation between the nodes, but we can use the node commands next and prev, which take a node name as an option, to do this:

1
2
3
4
5
6
7
8
9
@node node1 "First node"
@next node2
This text is in the first node.
@endnode

@node node2 "Second node"
@prev node1
This text is in the second node.
@endnode

Formatting text

We can format text using text commands such as b and i to turn on bold and italic, and ub and ui to turn them off:

1
2
3
@node node "A node"
Text can be @{b}bold, @{i}bold and italic, @{ub}italic, @{ui}or just plain.
@endnode

Hypertext links are created using the text command link. The link label, which appears as a button, is included as an option before the command name, while the link target and optionally a line number are included as options after the command name:

1
2
3
4
5
6
@node node "A node"
A link to @{"another node" link "node name"}.
A link to @{"a specific line in another node" link "node name" 10}.
A link to @{"a node in another file" link "Documents:AmigaGuide/another.guide/node name"}.
A link to @{"a different file type, using a dummy node name" link "image.iff/main"}.
@endnode

When creating a vertical list of links, different button widths can look messy. Some authors add spaces around the link label to ensure the buttons are all the same width. Other authors use two spaces as a link label, creating a column of identical square buttons, and then describe each link in the text following its button.

Whitespace handling

By default AmigaGuide viewers display whitespace exactly as it appears within the source text. If lines are too long to fit in the window, a horizontal scroll bar is displayed. Authors usually break lines so that a horizontal scroll bar is not needed when the document is viewed using the default Topaz font on a 640-pixel-wide screen.

Workbench 3.0 introduced the wordwrap command, as both a global command (applying to all nodes) and a node command. When the wordwrap command is used, lines will automatically wrap to prevent a horizontal scroll bar being displayed. Line breaks in the source text are preserved, so paragraphs must be written as a single line to prevent unwanted line breaks. This causes problems for viewers on old versions of Workbench, as paragraphs will then have no line breaks at all.

Workbench 3.1 introduced the smartwrap command, as both a global command (applying to all nodes) and a node command. When the smartwrap command is used, lines will automatically wrap to prevent a horizontal scroll bar being displayed. Single line breaks in the source text are ignored, while double line breaks or the text command par are used to create manual line breaks. The smartwrap command can be used without causing problems for viewers on old versions of Workbench by including line breaks in the source text as if smartwrap is unavailable, and using two line breaks instead of the par command to create a new paragraph.

Global commands

$VER: [information]

Specifies version information accessed through the AmigaDOS version command:

1
@$VER: example.guide 1.0 (2014-12-14)

(c) [information]

[Unused] Specifies copyright information:

1
@(c) 2014 Stephen Morley

author [name]

[Unused] Specifies the name of the author:

1
@author Stephen Morley

database

Identifies the file as an AmigaGuide document:

1
@database

endnode

Marks the end of a node definition:

1
@endnode

font [name] [size]

Specifies the font to use:

1
@font Example.font 12

height [rows]

[Unused] Specifies the number of rows in the tallest node:

1
@height 100

help [node]

Specifies the node to show when the Help button is clicked:

1
@help "help node"

If this command is not used, the Help button provides general help about browsing AmigaGuide documents.

index [node]

Specifies the node to show when the Index button is clicked:

1
@index "index node"

macro [definition]

[3.1] Defines a macro. The definition consists of a macro name followed by a substition, which may include substitutions using $1, $2, and so on. The macro is then used like a text command:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
@rem Define the macro:
@macro mylink @{"  " link $2} $1

@node node1 "A node"

@rem Use the macro:
@{mylink "Another node" "node2"}

@rem This is equivalent to:
@{"  " link "node2"} Another node

@endnode

master [path]

[Unused] Specifies the master document on which this document is based:

1
@master Documents:AmigaGuide/master.guide

node [name] [title]

Marks the start of a node definition:

1
@node node "Node title"

The name is used to link to the node. The title is shown in the window title bar.

onclose [path]

[3.1] Specifies an ARexx script to execute when the window is closed:

1
@onclose script.rexx

onopen [path]

[3.1] Specifies an ARexx script to execute when the window is opened:

1
@onopen script.rexx

rem [comment] / remark [comment]

Specifies a comment that is not displayed to viewers:

1
@rem Do not delete this node; it is referenced by other guides

smartwrap

[3.1] Turns on smartwrap:

1
@smartwrap

tab [spaces]

[3.1] Specifies the number of spaces generated by the text command tab:

1
@tab 2

width [columns]

[Unused] Specifies the number of columns in the widest node:

1
@width 100

wordwrap

[3.0] Turns on wordwrap:

1
@wordwrap

xref [path]

[3.0, Unused] Specifies another document to refer to:

1
@xref Documents:AmigaGuide/another.guide

Node commands

embed [path]

[3.0] Specifies a text file to be included at the location of the command:

1
@embed Documents:Text/text.txt

font [name] [size]

A node-specific version of the global command font.

help [node]

A node-specific version of the global command help.

index [node]

A node-specific version of the global command index.

keywords [keywords]

[Unused] Specifies keywords for the node:

1
@keywords AmigaGuide hypertext hyperlink

macro [definition]

[3.1] A node-specific version of the global command macro.

next [node]

Specifies the node to show when the Browse > button is clicked:

1
@next "next node"

If this command is not used, the Browse > button leads to the next node defined in the source text.

onclose [path]

[3.1] A node-specific version of the global command onclose; the script is executed when the node is closed.

onopen [path]

[3.1] A node-specific version of the global command onopen; the script is executed when the node is opened.

prev [node]

Specifies the node to show when the < Browse button is clicked:

1
@prev "previous node"

If this command is not used, the < Browse button leads to the previous node defined in the source text.

proportional

[3.0] Specifies that a proportional font should be used for this node:

1
@proportional

smartwrap

[3.1] A node-specific version of the global command smartwrap.

tab [spaces]

[3.1] A node-specific version of the global command tab.

title [title]

Specifies the node title, overriding the title specified with the node command:

1
@title "Node title"

toc [node]

Specifies the node to show when the Contents button is clicked:

1
@toc "contents node"

wordwrap

[3.0] A node-specific version of the global command wordwrap.

Text commands

[label] alink [path] [line?]

A version of the link command that opens a new window. From Workbench 3.0 onwards, the link does not open in a new window and this command behaves identically to the link command.

amigaguide

[3.1] Displays Amigaguide(R) in bold text:

1
@{amigaguide}

apen [pen]

[3.1] Specifies the foreground colour pen number to use from the next character onwards:

1
@{apen 1}

b

[3.0] Turns on bold text:

1
@{b}This text is bold.@{ub}

[label] beep

[3.0] Creates a button that, when clicked, issues a system beep (usually consisting of a beep sound and a flash of the screen):

1
@{"Beep" beep}

bg [colour]

Specifies the background colour to use from the next character onwards:

1
@{bg background}

Possible colours are back, background, fill, filltext, highlight, shadow, shine, and text.

body

[3.1] Restores default formatting from the next character onwards:

1
@{body}

bpen [pen]

[3.1] Specifies the background colour pen number to use from the next character onwards:

1
@{bpen 1}

cleartabs

[3.1] Restores default tab stops from the next character onwards:

1
@{cleartabs}

[label] close

Creates a button that, when clicked, closes the window:

1
@{"Close this window" close}

This command is useful in documents opened through the alink command. From Workbench 3.0 onwards, the button has no effect.

code

[3.1] Turns off wrapping other than when line breaks occur in the source text:

1
@{code}This text will not wrap onto multiple lines.

fg [colour]

Specifies the foreground colour to use from the next character onwards:

1
@{fg text}

Possible colours are back, background, fill, filltext, highlight, shadow, shine, and text.

[label] guide [path] [line?]

[3.0] A version of the link command that may only link to an AmigaGuide document.

i

[3.0] Turns on italic text:

1
@{i}This text is italic.@{ui}

jcenter

[3.1] Turns on centred text:

1
@{jcenter}This text is centred.

jleft

[3.1] Turns on left-aligned text:

1
@{jleft}This text is left-aligned.

jright

[3.1] Turns on right-aligned text:

1
@{jright}This text is right-aligned.

lindent [spaces]

[3.1] Specifies the indentation, in spaces, to apply from the next line onwards:

1
@{lindent 2}

By default no indentation is applied.

line

[3.1] Outputs a line break:

1
@{line}

This command is useful when smartwrap is used.

[label] link [path] [line?]

Creates a hypertext link:

1
2
3
4
A link to @{"another node" link "node name"}.
A link to @{"a specific line in another node" link "node name" 10}.
A link to @{"a node in another file" link "Documents:AmigaGuide/another.guide/node name"}.
A link to @{"a different file type, using a dummy node name" link "image.iff/main"}.

par

[3.1] Outputs two line breaks:

1
@{par}

This command is useful when smartwrap is used.

pard

[3.1] Restores default paragraph formatting from the next character onwards:

1
@{pard}

pari [spaces]

[3.1] Specifies the indentation, in spaces, to apply to the first line of paragraphs from the next paragraph onwards:

1
@{pari 2}

This value is added to any indentation specified with the indent command, and may be negative.

plain

[3.1] Restores default text formatting from the next character onwards:

1
@{plain}

[label] rx [path]

Creates a button that, when clicked, executes an ARexx script:

1
@{"Execute script" rx "script.rexx"}

[label] rxs [string]

Creates a button that, when clicked, executes an ARexx string:

1
@{"Execute string" rxs "Say 'hello'"}

settabs [spaces*]

[3.1] Specifies the tab stops, in spaces, to apply from the next character onwards:

1
@{settabs 2 4 6 8}

[label] system [path]

Creates a button that, when clicked, executes an AmigaDOS command:

1
@{"Format floppy disk" system "Format DF0:"}

[label] quit

Creates a button that, when clicked, closes the window:

1
@{"Close this window" quit}

This command is useful in documents opened through the alink command. From Workbench 3.0 onwards, the button has no effect.

tab

[3.1] Outputs a tab:

1
@{tab}

This command is affected by the tab and settabs commands. If neither is used, the tab is displayed as 8 spaces.

u

[3.0] Turns on underlined text:

1
@{u}This text is underlined.@{uu}

ub

[3.0] Turns off bold text:

1
@{b}Only this text is bold.@{ub}

ui

[3.0] Turns off italic text:

1
@{i}Only this text is italic.@{ui}

uu

[3.0] Turns off underlined text:

1
@{u}Only this text is underlined.@{uu}

Where now?

Found this useful? Share it:

Also in Articles: