So as you have seen in my previous posts I am working on my Tool for the Amiga Tool Jam.
As I have almost finished with that I have started writing the documentation and the instructions on how to use it.
Now you usually would write your instructions on a text file like a “readme.txt” or a “readme.md” file. However, I was introduced to a new file format called AmigaGuide.
What is AmigaGuide?
AmigaGuide files are files that would end with the extension “.guide”.
It is a hypertext document file format introduced on the Amiga in 1990. It is used to create documentation and help files for Amiga software.
How do I make an AmigaGuide file?
As AmigaGuide is a simple ASCII-formatted document, it can be edited by any normal text editor and viewed by any text viewer.
Making an AmigaGuide file
Making an AmigaGuide File requires some special characters.
The AmigaGuide First Line
AmigaGuide commands all begin with the ‘@’ symbol. To be recognized as an AmigaGuide document, the first line should include this text:
@database Amigaguide.guide
You can change it based on what your guide file is called but always make sure it has @database at the start.
There are three categories of commands: Global, Node, and Attributes.
Global Commands
Global commands are commands that apply to the entire document. They are usually placed at the beginning of the document but can be placed anywhere.
Some examples include @database,@author, @wordwrap, @copyright, and @$VER.
Node Commands
Node commands are commands that apply inside a node (after an ‘@NODE’ and before an “@ENDNODE”) and affect only the node in which they are used.
Some examples include @Node, @endnode, @Node, @Next, @Prev, @Toc.
Attribute Commands
Attributes may be 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.
Some examples include @{jleft}, @{jright}, @{jcenter}, @{b}, @{ub}, @{lindent (number)}, @{"Examples" Link "Examples"}.
The commands INDEX, HELP, NEXT, PREV, and TOC 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.
“TOC” also means “Table of Contents” and is used to specify the name of the node to be used as the table of contents for the document.
A basic AmigaGuide file would look like this:
@database Amigaguide.guide
@Node "Main" "Introduction"
@{b}Introduction@{ub}
This is a simple AmigaGuide file.
@{jleft}
@{" Examples " Link "Examples"}
@EndNode
@Node "Examples"
@Prev "Main"
@{b}Examples@{ub}
This is an example of a link to the @{lindent 3}@{"Introduction" Link "Main"}@{lindent 0} node.
@EndNode
Make sure that for your first Node, you have it as “Main” so that it is the first node that is shown when you open the file.
This is how it would look like when you open it.
And if you click the “Examples” button it should take you to the “Examples” node.
Now there are a lot more commands that you can use to make your AmigaGuide file look better and more organized.
Note: Also If you want to include ascii art on your AmigaGuide and it includes characters such as “\” make sure to add another “\” so that it shows up correctly.
You can find a list of the commands you can use with a amazing explanation here https://iamkate.com/code/amigaguide-reference/
Also, you can see the Amigaguide manual in AmigaGuide format. I know right? Convenient. Anyways you can find it here http://www.lysator.liu.se/amiga/code/guide/amigaguide.guide
AmigaGuide is a quite simple way to make guides and documentation for your Amiga software. It is quite easy to learn and use if you get the hang of it.
I hope this guide helped you and me understand how to make an AmigaGuide file.
I will be using this format for my documentation for my tool and I will also have a future blog post when I finally release my Tool!
Hope you enjoyed this short post and Thanks so much for reading :D