AmigaOS Documentation Wiki - User contributions [en]

Programming AmigaOS 4: The Development Environment

2016-08-29T14:55:56Z

Eldee Stephens: added a few links

''This article was adapted from Amiga Future magazine's series on developing for AmigaOS....''

We were shocked when we realised that while we've covered several subjects in programming for AmigaOS 4 in [http://www.amigafuture.de Amiga Future] there's been no extensive coverage of all of the many aspects. Additionally, since the release of AmigaOS 4, quite a lot of time has passed by, and during that time new programming treasures have sneaked into the SDK virtually unnoticed. It's been nine years since the authors did a similar series in "Amiga Magazin". So, we're launching a new 15-part series starting with a short peek at the SDK and the available development environments.

= SDK =

The Software Development Kit (SDK) for AmigaOS 4 has had some updates. You can find the latest version on from March 2010 on [http://www.hyperion-entertainment.biz/index.php?option=com_registration&view=files&parent=30&Itemid=63 Hyperion Entertainment's website]. The archive is easy to install and you can select which components you require. The base archives are always installed, and if you wish to use additional contributions you can select the appropriate archives. The installation has already been covered in Amiga Future 81 page 28 ([http://www.amigafuture.de/kb.php?mode=article&k=4174 link]) and issue 84 page 17 ([http://www.amigafuture.de/kb.php?mode=article&k=4325 link]). The SDK: assign holds all documentation ([[Autodocs:Main|Autodocs]]) and include files (include/include_h), the latter are required for developing your own code and they're included in the compiler's search path.

= Compiler =

The package installs the gcc compiler version 4.2.4, suitable for developing programs in C and C++. You can also create shared libraries, link libraries and shared object files (sobj). A detailed description of gcc and its command-line options can be found in SDK:Documentation.

= Development Environment =

Currently, the only complete development environment is [http://codebench.co.uk Codebench]. It allows you to easily join several files into a project, the makefile is created automatically. You can call the compiler directly from the DE.

There's the new [https://www.alinea-computer.de/produkte_details_en.php?product=stormc5ed StormC5 Editor], optimized for developers, with several features. We've covered this editor in Amiga Future's previous issue 102. StormC5 is planned to become a complete DE with project management and "integrated" compiler again.

Additional editors are [http://www.cygnused.de/index-en.php CygnusEd] and GoldEd. Also, the operating system's Notepad is generally suitable for creating code, probably limited to smaller/shorter programs however.

Generally, you can still use the older environments MaxonDevelop and [https://www.alinea-computer.de/produkte_details_en.php?product=stormc StormC4]. They feature project management and editors and provide for managing projects and editing the source code files. The required makefiles would need to be created manually however, the same applies to compiler or make calls.

= Documentation =

A constant issue is the inadequate, incomplete, and even some missing, documentation to the application programming interface (API). The first place to go would be the Autodocs files, at least providing short descriptions for each function, what parameters are to be passed to the function, which return values there are, and what purpose the function serves. The Autodocs should cover all functions although not always with up-to-date descriptions.

Fortunately, there is this wiki where you can find numerous descriptions and sample code. Additionally, you can try to [http://support.amigaos.net/ contact fellow developers]. If you require more of a tutorial or description of the architectural aspects you should look into the RKRMs revised and updated on this wiki. A look into [http://os4depot.net/index.php?function=browse&cat=development OS4Depot] can also provide helpful tools and sample code for developers. A short overview has been given in issue 79 page 25.

= The first step =

To avoid keeping this first part all theoretical we'd like to use a mini program to check whether AmigaOS version 4.1 (or better) is installed.

<syntaxhighlight>
/*
** check_os4.1.c : Pr¸fen auf AmigaOS 4.1 Umgebung / Check for AmigaOS 4.1 enviroment
** gcc check_os4.1.c -o check_os4.1
*/

#include <proto/exec.h>
#include <proto/dos.h>

int main()
{
int res;

if(SysBase->lib_Version >= 53)
{
IDOS->Printf("AmigaOS 4.1 ist vorhanden !\n");
IDOS->Printf("AmigaOS 4.1 is available !\n");
res = RETURN_OK;
}
else
{
IDOS->Printf("Das Programm benˆtigt AmigaOS 4.1\n");
IDOS->Printf("This program required AmigaOS 4.1\n");
res = RETURN_FAIL;
}

return( res );
}
</syntaxhighlight>

You can compile it directly from the console by

gcc check_os4.1.c -o check_os4.1

When run it'll output an appropriate text. This codeblock is suitable if you want to make sure that your program requires a specific OS version. For this, these values are significant: 50 stands for AmigaOS 4.0 preview, 51 for 4.0 final, 52 for 4.0 update 4 and the current 53 for 4.1. Generally, you can expect version 53 to be running.

= Outlook =

The next installment will get us right into coding. The first thing the Amiga starts is the kernel and for this we'll take a look at Exec and the basic functions it provides.

= Authors =

Written by Michael Christoph and Nils Petersen 
Copyright (c) 2013 Michael Christoph

AmigaOS Manual: AmigaDOS Understanding the Shell

2015-11-30T21:28:51Z

Eldee Stephens:

An AmigaDOS Shell is a special window on the Workbench screen that accepts text input, allowing you to communicate with AmigaDOS. The Shell is a type of Command Line Interface or CLI. This chapter describes the following:

= About the Shell =

You can communicate directly with AmigaDOS through a Shell console window, a text-only interface that accepts input entered from the keyboard. The Shell window looks and acts like a Workbench window with some exceptions:

* Icons dragged into the Shell window do not initiate a file move or copy operation; rather any icon dragged into the Shell window will cause the Shell to auto-type the icon's name and full path into the command prompt
* The mouse has somewhat limited use; it can be used for copy and paste operations, except within the ED and MEmacs text editors, or for selecting autocompleted commands from a pop-up menu if enabled in the Shell preferences
* Scroll gadgets work as you would expect, except that the length of Shell history captured may be limited by user preference
* The AmigaDOS Shell window uses a non-proportional font by default, normally the System Default Text font, e.g. DejaVu Sans Mono, specified by the Font Preferences editor.
* Any Workbench background patterns set in WBPattern do not appear in Shell windows

Like Workbench, several independent Shell windows can be open at the same time. While commands entered in one Shell are being executed, you can enter and execute different commands in another Shell window. You can also combine Shell windows into a single window, with each Shell session accessible via tabs. Figure 2-1 illustrates a Shell window opened on the Workbench screen:

[[File:DosFig2-1.png|center|frame|Shell Window with Tabs]]

= Opening Shell Windows =

Shell windows can be opened in one of several ways:

* Click on the Shell icon in the Workbench System drawer
* Click on the Shell icon in your AmiDock (if enabled)
* Use the NEWSHELL command described in Chapter 6
* Select 'New shell' from any already open Shell session
* Select 'Shell Here' from the 'New' submenu in any Workbench contextual pop-up menu

When a Shell window is opened:

* The window is highlighted, indicating that it is the current window
* A prompt appears, such as 1.SYS: >
* To the right of the prompt is a cursor, the default being a small highlighted rectangle

Like Workbench, only the currently selected Shell can receive input. To enter information in a different Shell, click in its window (or select its tab) to make it the current Shell session.

= Closing Shell windows =

Use one of the following four ways to close a Shell window:

* Select the close gadget
* Select 'Close' from the Project menu
* Enter the ENDCLI command
* Press Ctrl+\

We recommend closing Shell windows when you are finished with them. Any open window uses memory.

All non-detached programs that run from a Shell must be finished before you can close the window. You can tell that a program is still active if pressing Return does not produce a Shell prompt in the window. Although you can still enter commands into such a window, AmigaDOS does not respond to the commands until the running program is exited.

= Using the Shell =

Enter AmigaDOS commands at the Shell's text prompt. Include with the command any necessary information, such as file names or command options. Press Return at the end of each command line to execute the command. The Shell prompt reappears when the command is finished executing.

To see command output that has scrolled out of the Shell window, use the scroller gadgets to scroll up or down; you can also enlarge the window by selecting the Shell zoom gadget or using the sizing gadget. The Shell window will keep a full scrollback history of as many lines as you specify using the Console prefs tool. Figure 2-2 illustrates a Shell window before and after using the zoom gadget to display the entire output of an INFO command.

[[File:DosFig2-2a.png|center|frame|Current Output]]

[[File:DosFig2-2b.png|center|frame|Revealing Previous Output with the Scroller Gadget]]

== Command Line Editing and Control ==

To simplify entering and editing command line text, the AmigaDOS Shell provides the following editing key and key combination options:

{| class="wikitable"
| left arrow || Moves cursor one character to the left.
|-
| right arrow || Moves cursor one character to the right.
|-
| Shift+left arrow || Moves cursor to the beginning of the line.
|-
| Shift+right arrow || Moves cursor to the end of the line.
|-
| Backspace || Deletes the character to the left of the cursor.
|-
| Del || Deletes the character highlighted by the cursor.
|-
| Ctrl+H || Deletes the last character (same as Backspace).
|-
| Ctrl+M || Processes the command line (same as Return).
|-
| Ctrl+J || Adds a line feed.
|-
| Ctrl+W || Deletes the word to the left of the cursor.
|-
| Ctrl+X || Deletes the current line.
|-
| Ctrl+K || Deletes everything from the cursor forward to the end of the line.
|-
| Ctrl+Y || Replaces the characters deleted with Ctrl+K.
|-
| Ctrl+U || Deletes everything from the cursor backward to the start of the line.
|}

In addition, the Shell supports the following keys and key combinations:

{| class="wikitable"
| Space bar (or any printable character) || Suspends output (stops scrolling).
|-
| Backspace || Resumes output (continues scrolling).
|-
| Ctrl+C || Sends a BREAK command to the current process (halts the process).
|-
| Ctrl+D || Sends at BREAK command to the current script (halts the script).
|-
| Ctrl+F || Activates and brings Workbench program windows to the front.
|-
| Ctrl+S || Suspends output.
|-
| Ctrl+Q || Resumes output if it was suspended with Ctrl+S.
|-
| Ctrl+\ || Closes the Shell window. When console |/O is redirected to another device with * restores normal |/O.
|}

The Shell allows you to enter a command or other information while listing output. However, this stops the output until you press the Return key. The new command executes after the output is finished listing.

If you enter a new command or text and then choose to delete it, the original output resumes scrolling as soon as the last character is erased.

== Using the Command History ==

The Shell uses a 2 KB command line buffer to retain command lines, which provides a command history. Using this history you can recall previously entered command lines, edit them, and re-execute them. This lets you easily repeat a command or enter several similar commands. Figure 2-3 illustrates a series of commands stored in the command history buffer.

[[File:DosFig2-3.png|center|frame|Command History Buffer]]

The exact number of lines retained in the command line buffer varies depending on the length of the lines actually stored. When the buffer is full, the oldest lines are removed. You can access lines in the buffer with the up and down arrow keys:

{| class="wikitable"
| up arrow || Moves backward in the history buffer (earlier lines).
|-
| down arrow || Moves forward in the history buffer (later lines).
|}

For example, you can copy several .info files from one directory to another by enteringthe full command line with the complete path only once and then recalling the lines as many times as necessary, changing only the file name.

You can also search for the most recent occurrence of a specific command by entering the command line, or the beginning of it, and pressing Shift+up arrow (or Ctrl+R). For example, if you enter DIR and press Shift+up arrow, you are returned to the last command entered to perform a DIR of any directory. Pressing Shift+down arrow goes to the bottom of the command history buffer, leaving the cursor on a blank line.

== Copying and Pasting ==

You can copy and paste information from one console window, such as a Shell or ED window, to the same or another window. This done by selecting commands in the Edit menu, just like in most Amiga tools. Figure 2-4 illustrates copying and pasting from the Shell window to a Notepad window.

[[File:DosFig2-4a.png|center|frame|Copy]]

[[File:DosFig2-4b.png|center|frame|Paste]]

Use the mouse to highlight the area of text to be copied and pasted. Highlight the text to be copied by moving the pointer to the beginning of the text area, holding down the selection button, and dragging the mouse pointer to the end of the desired text. Release the selection button and press Right Amiga+C or select Copy from the Edit menu. The highlighted area is copied into the Clipboard and the area is unhighlighted. The text you copied can be repeatedly pasted into any application window that supports reading text from the Clipboard, such as the Shell, Notepad, and MultiEdit.

To position the cursor where you want to paste the text, move the mouse pointer to that location and click. Press right Amiga+V to paste the text.

{{Note|If a block of text is pasted into a Shell window, the Shell attempts to execute each line of the text as a command. This can have unpredictable results if the block of text has embedded returns and is not an AmigaDOS script.}}

== Working with the Shell ==

The following are tips for speeding your work with the Shell.

; Use command history and command line editing
: It sometimes takes several attempts using the same command before getting it right, especially when you are first learning how to use AmigaDOS. Use the arrow keys to recall a previous command and change only the part of the line that causes the problem to eliminate the need to retype the entire line.

; Use aliases
: Defining short aliases for commands you use often is another time-saver. It also eliminates the need to remember a long and/or complex series of options. For complete instructions, see the ALIAS command in Chapter 6.

; Omit unnecessary keywords
: For clarity, AmigaDOS command names and keywords throughout this book are often shown although they are optional. When you learn a command's format, however, you seldom need to include optional keywords.

; Do not use capital letters
: Command names, keywords, and assigned directories are shown in all upper case letters throughout this manual even though AmigaDOS is case-indifferent. This is done to distinguish the keywords from the file names and other information on the example command line. There is no need to use capitalization, except in commands that create a file or directory whose name you want to appear capitalized.

; Use implied CD
: This allows you to leave out the CD command, saving three keystrokes. Enter the only directory name, path, colon, or slashes at the prompt to change directories. For more information about changing directories, see the CD command in Chapter 6.

AmigaOS Manual: AmigaDOS Understanding the Shell

2015-11-30T21:28:40Z

Eldee Stephens:

AmigaOS Manual: AmigaDOS Understanding the Shell

2015-11-30T21:28:22Z

Eldee Stephens:

AmigaOS Manual: AmigaDOS Understanding the Shell

2015-11-30T21:24:14Z

Eldee Stephens:

An AmigaDOS Shell is a special window on the Workbench screen that accepts text input, allowing you to communicate with AmigaDOS. The Shell is a type of Command Line Interface or CLI. This chapter describes the following:

= About the Shell =

You can communicate directly with AmigaDOS through a Shell console window, a text-only interface that accepts input entered from the keyboard. The Shell window looks and acts like a Workbench window with some exceptions:

* Icons dragged into the Shell window do not initiate a file move or copy operation; rather any icon dragged into the Shell window will cause the Shell to auto-type the icon's name and full path into the command prompt
* The mouse has somewhat limited use; it can be used for copy and paste operations, except within the ED and MEmacs text editors, or for selecting autocompleted commands from a pop-up menu if enabled in the Shell preferences
* Scroll gadgets work as you would expect, except that the length of Shell history captured may be limited by user preference
* The AmigaDOS Shell window uses a non-proportional font by default, normally the System Default Text font, e.g. DejaVu Sans Mono, specified by the Font Preferences editor.
* Any Workbench background patterns set in WBPattern do not appear in Shell windows

Like Workbench, several independent Shell windows can be open at the same time. While commands entered in one Shell are being executed, you can enter and execute different commands in another Shell window. You can also combine Shell windows into a single window, with each Shell session accessible via tabs. Figure 2-1 illustrates a Shell window opened on the Workbench screen:

[[File:DosFig2-1.png|center|frame|Shell Window with Tabs]]

= Opening Shell Windows =

Shell windows can be opened in one of several ways:

* Click on the Shell icon in the Workbench System drawer
* Click on the Shell icon in your AmiDock (if enabled)
* Use the NEWSHELL command described in Chapter 6
* Select 'New shell' from any already open Shell session
* Select 'Shell Here' from the 'New' submenu in any Workbench contextual pop-up menu

When a Shell window is opened:

* The window is highlighted, indicating that it is the current window
* A prompt appears, such as 1.SYS: >
* To the right of the prompt is a cursor, the default being a small highlighted rectangle

Like Workbench, only the currently selected Shell can receive input. To enter information in a different Shell, click in its window (or select its tab) to make it the current Shell session.

= Closing Shell windows =

Use one of the following four ways to close a Shell window:

* Select the close gadget
* Select 'Close' from the Project menu
* Enter the ENDCLI command
* Press Ctrl+\

We recommend closing Shell windows when you are finished with them. Any open window uses memory.

All non-detached programs that run from a Shell must be finished before you can close the window. You can tell that a program is still active if pressing Return does not produce a Shell prompt in the window. Although you can still enter commands into such a window, AmigaDOS does not respond to the commands until the running program is exited.

= Using the Shell =

Enter AmigaDOS commands at the Shell's text prompt. Include with the command any necessary information, such as file names or command options. Press Return at the end of each command line to execute the command. The Shell prompt reappears when the command is finished executing.

To see command output that has scrolled out of the Shell window, use the scroller gadgets to scroll up or down; you can also enlarge the window by selecting the Shell zoom gadget or using the sizing gadget. The Shell window will keep a full scrollback history of as many lines as you specify using the Console prefs tool. Figure 2-2 illustrates a Shell window before and after using the zoom gadget to display the entire output of a LIST command.

[[File:DosFig2-2a.png|center|frame|Current Output]]

[[File:DosFig2-2b.png|center|frame|Revealing Previous Output with the Scroller Gadget]]

== Command Line Editing and Control ==

To simplify entering and editing command line text, the AmigaDOS Shell provides the following editing key and key combination options:

{| class="wikitable"
| left arrow || Moves cursor one character to the left.
|-
| right arrow || Moves cursor one character to the right.
|-
| Shift+left arrow || Moves cursor to the beginning of the line.
|-
| Shift+right arrow || Moves cursor to the end of the line.
|-
| Backspace || Deletes the character to the left of the cursor.
|-
| Del || Deletes the character highlighted by the cursor.
|-
| Ctrl+H || Deletes the last character (same as Backspace).
|-
| Ctrl+M || Processes the command line (same as Return).
|-
| Ctrl+J || Adds a line feed.
|-
| Ctrl+W || Deletes the word to the left of the cursor.
|-
| Ctrl+X || Deletes the current line.
|-
| Ctrl+K || Deletes everything from the cursor forward to the end of the line.
|-
| Ctrl+Y || Replaces the characters deleted with Ctrl+K.
|-
| Ctrl+U || Deletes everything from the cursor backward to the start of the line.
|}

In addition, the Shell supports the following keys and key combinations:

{| class="wikitable"
| Space bar (or any printable character) || Suspends output (stops scrolling).
|-
| Backspace || Resumes output (continues scrolling).
|-
| Ctrl+C || Sends a BREAK command to the current process (halts the process).
|-
| Ctrl+D || Sends at BREAK command to the current script (halts the script).
|-
| Ctrl+F || Activates and brings Workbench program windows to the front.
|-
| Ctrl+S || Suspends output.
|-
| Ctrl+Q || Resumes output if it was suspended with Ctrl+S.
|-
| Ctrl+\ || Closes the Shell window. When console |/O is redirected to another device with * restores normal |/O.
|}

The Shell allows you to enter a command or other information while listing output. However, this stops the output until you press the Return key. The new command executes after the output is finished listing.

If you enter a new command or text and then choose to delete it, the original output resumes scrolling as soon as the last character is erased.

== Using the Command History ==

The Shell uses a 2 KB command line buffer to retain command lines, which provides a command history. Using this history you can recall previously entered command lines, edit them, and re-execute them. This lets you easily repeat a command or enter several similar commands. Figure 2-3 illustrates a series of commands stored in the command history buffer.

[[File:DosFig2-3.png|center|frame|Command History Buffer]]

The exact number of lines retained in the command line buffer varies depending on the length of the lines actually stored. When the buffer is full, the oldest lines are removed. You can access lines in the buffer with the up and down arrow keys:

{| class="wikitable"
| up arrow || Moves backward in the history buffer (earlier lines).
|-
| down arrow || Moves forward in the history buffer (later lines).
|}

For example, you can copy several .info files from one directory to another by enteringthe full command line with the complete path only once and then recalling the lines as many times as necessary, changing only the file name.

You can also search for the most recent occurrence of a specific command by entering the command line, or the beginning of it, and pressing Shift+up arrow (or Ctrl+R). For example, if you enter DIR and press Shift+up arrow, you are returned to the last command entered to perform a DIR of any directory. Pressing Shift+down arrow goes to the bottom of the command history buffer, leaving the cursor on a blank line.

== Copying and Pasting ==

You can copy and paste information from one console window, such as a Shell or ED window, to the same or another window. This done by selecting commands in the Edit menu, just like in most Amiga tools. Figure 2-4 illustrates copying and pasting from the Shell window to a Notepad window.

[[File:DosFig2-4a.png|center|frame|Copy]]

[[File:DosFig2-4b.png|center|frame|Paste]]

Use the mouse to highlight the area of text to be copied and pasted. Highlight the text to be copied by moving the pointer to the beginning of the text area, holding down the selection button, and dragging the mouse pointer to the end of the desired text. Release the selection button and press Right Amiga+C or select Copy from the Edit menu. The highlighted area is copied into the Clipboard and the area is unhighlighted. The text you copied can be repeatedly pasted into any application window that supports reading text from the Clipboard, such as the Shell, Notepad, and MultiEdit.

To position the cursor where you want to paste the text, move the mouse pointer to that location and click. Press right Amiga+V to paste the text.

{{Note|If a block of text is pasted into a Shell window, the Shell attempts to execute each line of the text as a command. This can have unpredictable results if the block of text has embedded returns and is not an AmigaDOS script.}}

== Working with the Shell ==

The following are tips for speeding your work with the Shell.

; Use command history and command line editing
: It sometimes takes several attempts using the same command before getting it right, especially when you are first learning how to use AmigaDOS. Use the arrow keys to recall a previous command and change only the part of the line that causes the problem to eliminate the need to retype the entire line.

; Use aliases
: Defining short aliases for commands you use often is another time-saver. It also eliminates the need to remember a long and/or complex series of options. For complete instructions, see the ALIAS command in Chapter 6.

; Omit unnecessary keywords
: For clarity, AmigaDOS command names and keywords throughout this book are often shown although they are optional. When you learn a command's format, however, you seldom need to include optional keywords.

; Do not use capital letters
: Command names, keywords, and assigned directories are shown in all upper case letters throughout this manual even though AmigaDOS is case-indifferent. This is done to distinguish the keywords from the file names and other information on the example command line. There is no need to use capitalization, except in commands that create a file or directory whose name you want to appear capitalized.

; Use implied CD
: This allows you to leave out the CD command, saving three keystrokes. Enter the only directory name, path, colon, or slashes at the prompt to change directories. For more information about changing directories, see the CD command in Chapter 6.

File:DosFig2-2b.png

2015-11-30T21:23:26Z

Eldee Stephens: Eldee Stephens uploaded a new version of File:DosFig2-2b.png

File:DosFig2-2a.png

2015-11-30T21:23:04Z

Eldee Stephens: Eldee Stephens uploaded a new version of File:DosFig2-2a.png

2013-01-30T03:56:04Z

AmigaGuide 101

2013-01-29T18:53:17Z

Eldee Stephens:

''adapted from the original AmigaMail article by Jerry Hartzler''

== Introduction ==

Compared to other platforms, Amiga-based utilities that display on-line documentation are relatively weak. Until 1991, Amiga users had to rely on basic text viewing utilities like More, which lack the navigational capabilities of hypertext programs. In a hypertext environment, when the user wants more information on a subject, the user simply clicks on a word and the hypertext utility automatically cross references the subject. No type of hypertext-like utility was available on the Amiga--that is, until AmigaGuide came along.

AmigaGuide can display plain ASCII text files and AmigaGuide databases. An AmigaGuide database is a single file that consists of a set of documents called nodes. If you were to convert a book into an AmigaGuide database, a convenient way to organize the database is to make each chapter of the book into a node. Each node may contain references to other nodes (chapters) or databases (other books), using a link. When a user selects a link--which usually appears in the form of a button within the text--AmigaGuide dereferences the link and displays its node. This makes it easier for the user to find the information he is looking for because the user no longer needs to search through a document. AmigaGuide already knows where the information is.

Buttons within AmigaGuide can do other actions as well, such as execute Shell or ARexx commands. An ARexx port is also built into AmigaGuide providing users the means to support and control the utility. Therefore, like a book, an AmigaGuide database can display illustrations. It can go a step beyond by playing sounds and music, and by being truly interactive with the user, able to ask questions and evaluate responses.

This article was written to familiarize you with AmigaGuide and the format of its databases.

== Setting up AmigaGuide ==

AmigaGuide consists of the AmigaGuide utility and an Exec library called amigaguide.library. AmigaGuide should be placed in the SYS:Utilities drawer and amigaguide.library placed in the Libs: drawer. As of Release 3, the OS comes with a utility called MultiView that understands and displays AmigaGuide databases. MultiView requires amigaguide.datatype and datatypes.library in order to display AmigaGuide databases.

AmigaGuide can run from the Workbench or the Shell. To run from Workbench, the default tool of an AmigaGuide database or text icon should be set to '''AmigaGuide'''.

From the Shell, use the following command template:

AmigaGuide <my_DataBase>

where <my_DataBase> is the name of the AmigaGuide database or text file to display.

For example:

1> AmigaGuide Autodocs

attempts to open the Autodocs database. In its search for a database, AmigaGuide will first look in the current directory and then through the AmigaGuide path for the database.

The AmigaGuide path is a global environment variable. AmigaGuide stores its environment variables in the ENV:AmigaGuide directory assigned in RAM:.

The variable named path contains the list of directory names that AmigaGuide will search through when it attempts to open a database. Directory names are separated by a space. The path variable is set and stored in the ENV:AmigaGuide directory through the use of the AmigaDOS SetEnv command (Note that as of Release 3, if the AmigaGuide directory does not exist, SetEnv will not create it).

For example:

1> SetEnv AmigaGuide/Path "Workbench:Autodocs Workbench:Includes"

Of course all variables set in RAM: disappear once the computer is turned off. To prevent this, copy the file ENV:AmigaGuide/Path to the ENVARC:AmigaGuide directory. The system copies the ENVARC: directory to ENV: upon start-up.

The MultiView utility uses the amigaguide.datatype which uses this the environment variable as its path.

== The AmigaGuide Window ==

AmigaGuide displays text within an Intuition window. The window contains scroll bars, buttons and pull-down menus making it easy to browse, search and print text.

[[File:Amigaguide.png]]

Along the top edge of the AmigaGuide window is a row of six navigation buttons:

* Contents: This button displays the Table Of Contents for the current database or node. See the @NODE and @TOC commands below.

* Index: This button displays the Index for the current database. See the @INDEX command below.

* Help: By default, this button displays the database named help.guide in the s: directory. Under 3.0, the database is named amigaguide.guide in the Help:<country>/sys directory. This database contains help in using AmigaGuide.

* Retrace: This button goes back to the previous node.

* Browse: These buttons step through the nodes in sequential order (the order they appear in the database).

== AmigaGuide Databases ==

Creating an AmigaGuide database is quite simple. An AmigaGuide database is basically an ASCII text file, embedded with commands to tell AmigaGuide what to do. Let's take a look at the commands used in AmigaGuide and then make up a simple database.

There are three types of AmigaGuide commands. Database commands break up a document into nodes. Node commands set attributes within a node. Action commands are only found within a special node command called a '''link point'''. As the name implies, action commands perform some action.

=== Database Commands ===

Database commands should not be used within the nodes themselves. They must start in the first column of a line. If a line in an AmigaGuide database begins with an at (@) sign, then AmigaGuide interprets the line as a command. Although the AmigaGuide commands appear here in upper-case, AmigaGuide commands are not case sensitive.

* @DATABASE <name> - This command identifies a file as an AmigaGuide database. It must be the first line of the database.

* @NODE <name> <title> - This command indicates the start of a node. The first node of a database should be named MAIN. MAIN is typically the master table of contents for the database (see the @TOC node command in the next section). When AmigaGuide displays the node, it displays <title> in the window's title bar. If there are any spaces in the <title>, it must be in quotes. A node name cannot contain spaces, tabs, colons (':') or slants ('/').

* @DNODE <name> - This command indicates the start of a dynamic node. Dynamic nodes are beyond the scope of this introductory article and therefore are not discussed here.

* @INDEX <node name> - This command tells AmigaGuide which node to use as the index for the database. When the user hits the '''Index''' button at the top of the AmigaGuide window, AmigaGuide will display the node specified by this command. The node can be in another database. If the node is in another database, the node name is the file name of the database followed by a slant (`/`), followed by the name of the node in the other database. For example, to access the MAIN node in another database called other_database, the link point looks like this:

@{"my label" LINK other_database/MAIN}

''The name of the other database can contain a full path to the other database. If it doesn't, AmigaGuide will search the AmigaGuide path for the other database.''

* @REMARK <remark> - This commands lets you add programmer remarks to a database. AmigaGuide ignores the remarks.

=== Node Commands ===

These commands are only valid within a @NODE. They must start in the
first column of a line unless otherwise noted.

* @ENDNODE <name> - This command ends a node.

* @TITLE <title> - AmigaGuide displays <title> in the node's window title bar. It must start at the beginning of a line. This command isn't necessary if you use the <title> option in @NODE.

* @TOC <node name> - This command tells AmigaGuide which node to display when the user hits the Contents button while displaying this node. If a node does not have a @TOC command, the table of contents defaults to MAIN. The <node name> can be in another database. See the @INDEX command in the [[#Database Commands|Database Commands]] section for more information on the format of <node name>.

* @PREV <node name> - The Browse buttons can be reprogrammed so as not to step through the nodes in sequential order. For example, if this command appears in a @NODE, AmigaGuide will display the <node name> node when the user selects the '''< Browse''' button while in the current node. The <node name> can be in another database. See the @INDEX command in the [[#Database Commands|Database Commands]] section for more information on the format of <node name>.

* @NEXT <node name> - Similar to @PREV but will display the <node name> node when the user selects '''Browse >''' button while in the current node. The <node name> can be in another database. See the @INDEX command in the [[#Database Commands|Database Commands]] section for more information on the format of <node name>.

* @{"<label>" <action command>} - This command is referred to as a link point. AmigaGuide makes the string <label> into a button. The <label> must be enclosed by quotes. When the user hits that button, AmigaGuide carries out <action command> (see the next section of this article for a description of action commands). A link point does not have to start in the first column, it can appear anywhere on a line.

=== Action Commands ===

These commands are for use with the link point command described in the [[#Node Commands|Node Commands]] section of this article.

* LINK <node name> <line#> - This command loads and displays the <node name> node at the line number specified in <line #>. The <line #> parameter is optional and it defaults to zero. The node can be in another database. The <node name> can be in another database. See the @INDEX command in the [[#Database Commands|Database Commands]] section for more information on the format of <node name>.

''The <line #> parameter is optional and it defaults to zero. The default line number is line zero.''

* RX <ARexx command> - This commands executes the ARexx macro named in <ARexx command>.

* RXS <command> - This commands executes the ARexx string file named in <command>.

* SYSTEM <command> - This commands executes the AmigaDOS command named in <command>.

* QUIT - When AmigaGuide encounters this command is shuts down the current database.

== A Working Database ==

As an example, Let's make the text file below into a simple AmigaGuide database. The simple database will consists of a single node.

<nowiki> What is a user interface? This sweeping phrase covers all
aspects of communication between the user and the computer. It
includes the innermost mechanisms of the computer and rises to
the height of defining a philosophy to guide the interaction
between human and machine. Intuition is, above all else, a
philosophy turned into software. See the Amiga ROM Kernel
Reference Manual: Libraries for more information.

Intuition screens are the basis of any display Intuition can
make. Screens determine the fundamental characteristics of the
display such as the resolution and palette and they set up the
environment for multiple, overlapping windows that makes it
possible for each application to have its own separate visual
context.

Windows are rectangular display areas that open on screens.
The window acts as a virtual terminal allowing a program to
interact with the user as if it had the entire display all to
itself. Windows are moveable and can be positioned anywhere
within the screen on which they exist. Windows may also have a
title and borders containing various gadgets for controlling
the window.

Gadgets are software controls symbolized by an image that the
user can operate with the mouse or keyboard. They are the
Amiga's equivalent of buttons, knobs and dials.

Menus are command and option lists associated with an
application window that the user can bring into view at any
time. These lists provide the user with a simple way to access
features of the application without having to remember or enter
complex character-based command strings.</nowiki>

If AmigaGuide displayed the file above, it would appear without any buttons linking it to text files or databases. To mark this file as an AmigaGuide database, add the @DATABASE command. As mentioned earlier, it must start on the first line in the first column of the file.

Since there will be no index for this database, the next command can be a @NODE. For AmigaGuide to open a database, it must contain a node. Since this will be the first node in the database, it should be named MAIN.

At the bottom of the file, on a separate line, add the @ENDNODE command. This tells AmigaGuide that the current node ends here. All nodes must contain an @ENDNODE command.

This is what we have so far:

@DATABASE
@NODE MAIN
What is a user interface? This sweeping phrase covers all
.
.
.
complex character-based command strings.
@ENDNODE

The file is now an AmigaGuide database. However, since the database has only one node and has no link points, the database will still appear as plain text. Also, AmigaGuide will ghost all of the navigation buttons. The database can be broken into smaller nodes if desired. Normally such a short file would not need to be broken up, but it makes a good example.

One important issue to consider while designing an AmigaGuide database is how to lay it out. Some thought should go into the break-up of a document into manageable nodes, and how these nodes relate--and eventually link--to one another. Each node should consist of information dealing with one topic and should contain links to other related nodes.

Notice that the example text is about Intuition, but each paragraph discusses a different topic of Intuition. The first paragraph is an overview followed by four paragraphs: one each on screens, windows, gadgets and menus. This organization makes it convenient to make each paragraph a node with a table of contents in the beginning:

<nowiki> Intuition Table of Contents

Introduction
Screens
Windows
Gadgets
Menus</nowiki>

Since the Table of Contents node is first, it is the MAIN node. The other paragraphs follow the MAIN node, each in their own separate node. So as not to confuse AmigaGuide, each node within a database must have a different name.

<nowiki> @DATABASE
@NODE MAIN "Intuition Table of Contents"
Introduction
Screens
Windows
Gadgets
Menus
@ENDNODE

@NODE Intro "Introduction"
What is a user interface? This sweeping phrase...
@ENDNODE

@NODE Screen "Screens"
Intuition screens are the basis of any display...
@ENDNODE

@NODE Window "Windows"
Windows are rectangular display areas that open...
@ENDNODE

@NODE Gadget "Gadgets"
Gadgets are software controls symbolized by an...
@ENDNODE

@NODE Menu "Menus"
Menus are command and option lists associated...
@ENDNODE</nowiki>

When AmigaGuide loads the database above, AmigaGuide displays the MAIN node with the title string Intuition Table of Contents in the window's title bar. As the user clicks the Browse buttons at the top of the AmigaGuide window, AmigaGuide steps through each node in the database, displaying each paragraph. Notice that each node in the database uses the window title parameter. As the Browse buttons step through the database displaying the different nodes in sequence, the AmigaGuide window title changes to match the title from the current node.

An important limitation of the database above is the only way to access the different nodes is using the ``Browse'' button to step through them in the order they appear in the database. The database still has no buttons within the nodes to link to other nodes.

== Using Link Points ==

The link point command is probably the most commonly used command in a database. With it you can make a word in one node reference another node. For example, in the Table of Contents node from the previous example, you can make each entry from the table into a button that references its respective node.

The template for a link point is:

@{<label> <action command>}

The label parameter is the word or phrase in a database that is made into a button, and the action command is the action AmigaGuide takes when the user clicks the button. For our example, we want each topic in the table of contents to be a label and the action command for each to be a LINK command. The LINK command loads and displays another node.

@{<label> LINK <name> <line#>}

For example, if you change the word Introduction from the Table of Contents node into a link point it would look like this:

@{"Introduction" LINK Intro}

The <label> string must be in quotes. If you load the database into AmigaGuide after making the change above, the word Introduction would appear as a button on the Table of Contents screen. If the user clicks on the Introduction button, AmigaGuide displays the node named Intro.

Unlike other AmigaGuide commands, link points do not need to start in the first column. This makes it easy to indent a button from the left edge of the window and also to embed a button within a block of text.

Link points can also link to nodes in other databases. As an example, consider the following excerpt from the Intro node:

philosophy turned into software. See the Amiga ROM Kernel Reference
Manual: Libraries for more information.

If an AmigaGuide database of Amiga ROM Kernel Reference Manual: Libraries was readily available, it would be convenient if the word ''Libraries'' from the excerpt was a button, linking the word ''Libraries'' directly to the Libraries manual database. If the Libraries manual database was named Libraries_Manual and it was in the current AmigaGuide path, to make the word Libraries from the Intro node into a link point that opens the Libraries_Manual database, change the excerpt above to the following:

philosophy turned into software. See the Amiga ROM Kernel
Reference Manual: @{"Libraries" LINK Libraries_Manual/Intro} for more information.

In the example above, when the user selects the Libraries button, AmigaGuide will try to display the MAIN node from the database called Libraries_Manual. AmigaGuide will first look for Libraries_Manual in the directory where the example database resides. If it's not there, AmigaGuide searches through its path for the database. Alternately, you can supply a full path name to Libraries_Manual.

A link point can also be used to display a picture. For example, to display an ILBM image of a Workbench screen from the Screen node, use the SYSTEM action command:

@{"Picture of a Workbench Screen" SYSTEM sys:utilities/Display sys:Workbench.pic}

From the command above, when the user click the ''Picture of a Workbench Screen'' button, SYSTEM executes the Display utility. Display shows the ILBM file sys:Workbench.pic. Because Display is merely a shell command, you can substitute your own ILBM viewer for Display.

Below is the finished database with a few more interactive link points.

<nowiki> @DATABASE
@NODE MAIN "Intuition Table of Contents"
@{"Introduction" LINK Intro}
@{"Screens" LINK Screen}
@{"Windows" LINK Window}
@{"Gadgets" LINK Gadget}
@{"Menus" LINK Menu}
@ENDNODE

@NODE Intro "Introduction"
What is a user interface? This sweeping phrase covers all
aspects of communication between the user and the computer. It
includes the innermost mechanisms of the computer and rises to
the height of defining a philosophy to guide the interaction
between human and machine. Intuition is, above all else, a
philosophy turned into software. See the Amiga ROM Kernel
Reference Manual: @{"Libraries" LINK Libraries_Manual/Intro} for more information.
@ENDNODE

@NODE Screen "Screens"
Intuition screens are the basis of any display Intuition can
make. Screens determine the fundamental characteristics of the
display such as the resolution and palette and they set up the
environment for multiple, overlapping @{"windows" LINK Window} that makes it
possible for each application to have its own separate visual
context.

@{"Picture of a Workbench Screen" SYSTEM sys:utilities/Display sys:Workbench.pic}

@ENDNODE

@NODE Window "Windows"
Windows are rectangular display areas that open on @{"screens" LINK screen}. The
window acts as a virtual terminal allowing a program to interact
with the user as if it had the entire display all to itself.
Windows are moveable and can be positioned anywhere within the
screen on which they exist. Windows may also have a title and
borders containing various @{"gadgets" LINK Gadget} for controlling the window.
@ENDNODE

@NODE Gadget "Gadgets"
Gadgets are software controls symbolized by an image that the
user can operate with the mouse or keyboard. They are the
Amiga's equivalent of buttons, knobs and dials.
@ENDNODE

@NODE Menu "Menus"
Menus are command and option lists associated with an
application @{"window" LINK Window} that the user can bring into view at any
time. These lists provide the user with a simple way to access
features of the application without having to remember or enter
complex character-based command strings.
@ENDNODE</nowiki>

Although this is a small sample and only a few basic commands are used, it is a good start to making your own AmigaGuide database.

== Troubleshooting ==

To make it easier to create a bug-free database, below is a list of common mistakes made when editing an AmigaGuide database.

As with any type of programming, errors are bound to crop up. One of the most common mistakes is spelling errors. Always double check your spelling of commands. Also, make sure all commands that should begin in the first column do so.

*Symptom: AmigaGuide displays a database as a text file. For example, instead of a button, AmigaGuide displays the link point command that was supposed to display the button.
*Cure: AmigaGuide does not think the file is an AmigaGuide database. Check that the first line of the file is the @DATABASE command and that it starts in the first column.

*Symptom: When displaying a database node, AmigaGuide displays nothing in its window.
*Cure: Either the @ENDNODE command is not present in the node or the @ENDCODE command does not start in the first column.

*Symptom: AmigaGuide does not display a button or its label.
*Cure: The <label> parameter in the link point is missing or not enclosed in quotes.

*Symptom: When the user selects a button, AmigaGuide flashes the screen and displays the error message "Couldn't locate <node>".
*Cure: AmigaGuide cannot locate the node specified in the button's link point command. If the link point command points to a node in another database, the database must be in the AmigaGuide path or the node must contain the full path name to the database. The link point command also require a NODE name as the last parameter in the path separated by a slant (/). If the file is only text and not an AmigaGuide database, its path name should end with '''/MAIN'''. If a node or file has any spaces in its name, the path name must be enclosed within quotes.

*Symptom: AmigaGuide flashes the screen when a button is selected but displays no error message.
*Cure: AmigaGuide does not recognize the <action command> parameter in the link point, or AmigaGuide cannot locate the specified node (see the cure above).

*Symptom: AmigaGuide does not fully display a button.
*Cure: Check that all of the link points end with a closing brace (}). Note that there is a bug in AmigaGuide that can crash the system if a link point does not end with a closing brace.

*Symptom: AmigaGuide will not load a database and displays a "Can't find Node" requester.
*Cure: All databases must contain at least one node. If the file is short, all the text can be in one node called '''MAIN'''. If you do not wish to make the file a database at all, remove the @DATABASE command.

*Symptom: AmigaGuide does not allow the the user to browse the database to its end. It either stops browsing before reaching the last node, or it gets caught in an endless loop, cycling through a number of nodes.
*Cure: At least two nodes within a single database have the same name. Every node must have a different name unless they are in separate databases.