Getting to understand AmigaGuide Documents:
               -------------------------------------------
                            By Guy Nathan

On a regular basis I come in contact with programmers who still don't
know how to create AmigaGuide documents. For those who still dont
understand how to create it themselves, and instead of using programs
such as AmigaGuide Writer(c), GuideMaker(c), and the well known title
Heddley, I have come to your rescue <;^)>. Writing your own Guides is
really not as hard as some perceive it to be, and you will find like
me that making AmigaGuide documents can be done by anyone, and is
actually fairly powerful!

An AmigaGuide document always has to start with a few lines of data
for both the AmigaGuide reader to be able to use it, or file a file
type program to be able to identify it. They first one is the
simplest, and uses the following syntax:

                   '@database "<database name>"'

This has to ALWAYS be the first line of your AmigaGuide document.
The database name can be anything you like, but is usually the
filename, and should be in quotes.

What comes next is optional, but allows for more versatility and
readability (?) when others are reading your AmigaGuide documents.
They are as follows:

* '@(c) "<Copyright> <Author Name>"'         * WORKBENCH 3.0+ * 
  eg. '@(c) "Copyright (C) G. Nathan"

  This option allows you to put in copyright information.

* '@$VER: <Standard C= Version Format>'      * WORKBENCH 3.0+ * 
  eg. '@$VER: HelpMe.Guide 1.0 (10.09.99)'

  This option is useful for documents where people check which
  version of the documentation they have. It uses the standard
  Commodore Version format. In the example given the document
  name is given, the version number, and the date it was created.

* '@AUTHOR "<Author Name>"'                  * WORKBENCH 3.0+ *
  eg. '@AUTHOR "Guy Nathan"'

  This option allows you to place information as to who wrote
  the AmigaGuide document. The name should be placed inbetween
  the quotes.

* '@MASTER <FileName>'                        * ADVANCED *
  eg.'@MASTER Documents/HelpMe.Guide'

  This option is compulsary if you are linking several AmigaGuide
  documents together and contains the file name of the main file.
  This is mainly used when the primary file is an index/contents
  file. Also used in conjunction with 'Contents' button.

* '@INDEX <Index Name>'
  eg. '@INDEX Main'

  This is used for customizing which page the document goes to
  when the button 'Index' is pressed. It defaults to the 'Main'
  page.

* '@HELP <Filename/Node(Page) Name>'
  eg. '@INDEX HelpPage'

  This option is used for when you want your own custom help
  page when the user presses the 'Help' button. If this option
  is used it will go straight to that page name. If you wish
  to use an external AmigaGuide file which has help information
  in it you can place the path and filename of it here.

* '@FONT <FontName> <Font Size>'             * WORKBENCH 3.0+ *
  eg. '@FONT Helvetica.font 12'

  This option is used for customizing the look of the document.
  Remember if using this option if the user is to see the document
  as youve intended it to look you have to include the font with
  the document, as they may not have the font and the document
  can look terrible. 

* '@WORDWRAP'                                * WORKBENCH 3.0+ *

  This option turns word wrap on (as it defaults to off), and if
  it is currently on (which it wont be when a document is first
  opened) will switch it off.

* '@WIDTH <Number of Characters>'             * ADVANCED *
  eg. '@WIDTH 80'

  This option customizes the number of characters/letters per line
  it will display. It defaults to 80.

* '@HEIGHT <Number>'                          * ADVANCED *
  eg. '@HEIGHT 255'

  This option customizes the output of the document. This option
  is really never necessary. But will basically determine the
  size of the AmigaGuide window.

* '@REMARK <Remark>'
  eg. '@REMARK This is where I do X and Y'

  This option is not displayed to the user, but is for the use of
  the author for making comments/remarks.

The above options can not only be used in the beginning of
document though, and can be customized for any page you like.
It should be remembered though that doing it on a single page
will affect all sub-pages connected to it but not affect
previous pages.

Now to the document itself (:^)). An AmigaGuide document from
this point on can be merely text and nothing more, but in doing
so you are losing alot of its power. What ever you decide to
do though ALL AmigaGuide documents should start with the
following line:

    '@NODE <First Page Name> "<Title to be used in Window>"'
         eg. '@NODE Main "Main Page - How to Help Me"'

This sets up the first page of your document with its own
personalised page name, recognizable, and linkable from any
other point in the AmigaGuide document, and also gives a
title to be used in the window of that page. 'NODE' is
merely another name for page or section. If you wanted to
place the title of the page seperately add the following line:

           '@TITLE "<Title to be used in Window>"'
          eg. '@TITLE "Main Page - How to Help Me"'

The above example gives the title to be used in the window of
that page.

If you were to now insert your document here with nothing more,
you must place at the end of the document the following:

                     '@ENDNODE'

The above is a requirement for all pages/sections you start in
AmigaGuide document. Failing to do so will make the reader fail
to recognise the page even exists. Simple things like these are
common in creating these documents yourself.

For those of you who have seen an AmigaGuide document before will
have undoubtably seen the buttons which the user can click on
linking them to other parts of the document. Implementing these
is simple, but explaining it can be hard ;). An example of this
is as follows:

   '@{"<Button Text>" LINK <Node Name>} <Additional Text>'
 eg. '@{" Introduction " LINK Introduction } The Introduction'
  
      which would produce an output looking something like

               '< Introduction > The Introduction'
                        |
                This is a button

What the above line has done is created a button on the page
where it is viewed with the words ' Introduction ' on it, and 
a link to a node (page/section) called 'Introduction'. It also 
has the words 'The Introduction' to the right of the button.
The <Node Name> MUST be the correct name or it will either go
to the wrong page, or do nothing! 

The above link to a different node (page/section) is merely a
simple example of what the buttons can do! The button can also
be used to view pictures, listen to sounds, run executables,
run Arexx scripts and more! As you can see, there is really
quite alot of power which can be used here.

What you actually do here will depend on several factors.

Factor 1:
When using in-line images and sounds in your AmigaGuide documents
you must remember that the reader must also have the same
datatypes as you. A basic AmigaGuide setup supports IFF ILBM
images and IFF 8SVX sound samples, so it is recommended if you
plan to use in-line images to make sure your files are in this
format.

Factor 2:
If you want to make sure they can view and listen to whatever
is included it will mean the inclusion of a seperate executable
(program), which will also co-incidentally both increase the
archive size, and will put limits on what executables can be
used (ie. the inclusion of a 040 only viewer will restrict
readers of your documents to 040 owners only). Inclusion of
programs such as PPShow (c) Nico Francois, is usually the best
idea if you have many foreign image formats (eg. JPEG, GIF,
and the likes) and definately a must if you want to include
Animations with your document.

Factor 3:
The use of Arexx scripts and the like must be able to work on
the users system and they must have Arexx installed. Arexx
scripts aren't as commonly used.

After considering the above factors, and choosing to use images
or sounds or executables in your AmigaGuide document, you may
want to know how to implement this. It is done as follows:

* '@{"<Button Text>" LINK "<Path/Filename>"} <Additional Text>'

* '@{"<Button Text>" SYSTEM "<Path/Filename>"} <Additional Text>'
  eg. '@{" Run Donkies " SYSTEM "Exe/Donkies"} Fun donky game'

  This option is of similar syntax (design) to how you would use
  a button to jump to another node/page. The difference is the
  'SYSTEM "<Path/Filename>"'. 'SYSTEM' tells the AmigaGuide
  reader that it should execute the command in "<Path/Filename>".
  
   
Additional Note:
In designing names for your nodes, you should never leave spaces 
in the name, eg.

   '@NODE I Am Here "Help Me Guide - I Am Here"' <WRONG>

Instead it is recommended that you name the node as follows:

  '@NODE I_Am_Here "Help Me Guide - I Am Here"' <CORRECT>