GuideGen.guide AmigaGuide doc

GuideGen and this documentation file are

(C) Copyright 1993 Justin Miller, P.O. Box 17, Imbler, OR  97841

GuideGen is Shareware and may be freely distributed providing that:

    1)	This documentation file and copyright notice is included

    2)	Neither the program or this documentation file have been
	modified

    3)	Any charge made for its distribution does not exceed
	double that of which DevWare, Inc. of Poway, CA charges
	for freely distributable disks

If you find this program useful, please send $5 to the above address.

GuideGen requires Release 2 or later of the Amiga OS.

Table of Contents:

	What is GuideGen
	General Info and Warnings
	Creating a New Guide
	Opening a Guide
	Selecting a Guide
	Adding a Node
	Removing a Node
	Changing a Node its Title
	Moving a Node
	Editing a Node its Text
	Creating a Button
	Deleting a Button
	Linking a Button
	Unlinking a Button
	Saving Guides
	Preferences
	Quiting

GuideGen is a utility to generate AmigaGuide databases.  It allows you
to add and remove nodes, edit each node's text, arrange the node's order,
and create buttons and link them to other nodes, potentially in other files.

For more information on the AmigaGuide file format, see "AmigaGuide 101"
in the March/April 1993 issue of AmigaMail (Volume II), a publication
put out by Commodore for developers.  If you do not have this, contact
Commodore about obtaining it, or other AmigaGuide reference material.

GuideGen is only capable of generating buttons which link to nodes in
other guide files.  Buttons to execute a command or Rexx script will
be left in the text undisturbed.

LINK type buttons, however, are currently limited to a single word;
if you manually enter buttons whose button text consists of several
words, they may be lost if you attempt to edit that Node's text, from
within GuideGen.  As long as you do not edit that node's text, however,
the buttons should be treated normally, and correctly written out.

You should not name any node main.  GuideGen will automatically create a
Main Node which is a Table of Contents allowing you to access all of the
other nodes quickly (through buttons).  This automatic Table of Contents
generation cannot be disabled.

You can, of course, manually edit the guide files that GuideGen creates.
All you need to do this is a text editor (MEmacs, included with the system
software is ideal).  One common use for this is to break up the Table of
Contents into several subtables to facilitate finding information in large
databases.

To create a new guide in GuideGen click the New button in the lower
right-hand side of the GuideGen window.  A new guide will be added to
the files list, and selected.  At this point, you may enter nodes for it,
and once you have nodes, you can create buttons.

To open a guide, click on the Open button.  The open button is the right
button below the Files ListView.  It looks like an up arrow above a file
Requester.  When you click on this button, an ASL file requester will appear.
Select the guide you wish to open in this file requester.  The guide will
be loaded, added to the Files list, and selected, ready to be editted.
Note that any guides to which the guide you opened links will automatically
be loaded also.

At any time, the guide you are currently editting will be displayed in the
File display in the top left corner of the window. If you have several
guides open, and wish to edit a different one, you should select the Choose
Guide button.  The Choose Guide button is the left button below the Files
ListView.  It looks like a down arrow above a picture of the GuideGen
window.  When you click this button your pointer will change to a arrow
above the word use.  Click on the guide which you wish to edit in the
FileList ListView.  That guide will then become the selected guide, and its
name will appear in the File display in the upper left corner of the
window.

To add a node, select the file which you wish to add the node to.  If you
have not opened any files, or created a new guide, you will have to do so
before adding a node.  Once the file you wish to add the node to is open
and selected, click the + button to the right of the left Nodes list. Your
cursor will be placed in the string gadget beneath the list.  Enter the
node's name here.  The nodes name can contain any characters, including
spaces and punctuation.  The name you enter here will be the node's title.
The nodes nodename will be the title sans punctuation and spaces.  Once you
have entered the node's title, hit return.  The new node will be added to
the bottom of the Node List.  See also:  Moving nodes, and Editing node
text.

To remove a node, select it from the left Node list.  Then click the -
button. The Node and all its buttons, and all buttons that link to it, will
be deleted.

To change a node's title, select it in the left Node List.  Then click in
the string gadget below the list.  A cursor will appear.  Edit the title to
read as you would like, then hit return.  The node's title will be changed.

To move a node, select the node you wish to move in the left Node list.
Then use one of the arrow gadgets below the left Node list.  The single up
and down arrow gadgets will move the node up one and down one respectively.
The double up and down arrow gadgets will move the node to the top of the
file and bottom of the file respectively.

To edit a node's text, select the node whose text you wish to edit in the
left Node list.  Then click the Edit button.  The Edit button looks like a
pen writing on paper and is below the left Node list.  The text editor of
your choice (which defaults to MEmacs) will appear with the node text, sans
any button definitions and the NODE and ENDNODE commands.  Make any changes
to the text you would like.  Save the file using the file name assigned to
it when it was loaded, and exit the text editor.  The nodes text will now
be changed.  See also Preferences for information on selecting the text
editor to be used.

To create a button, select the node in which you want to create a button
in the left Nodes list.  An alphabetized list of all the words in that
node's text will appear in the Words list below the Buttons list.  Select
the word which you want to use as a button.  Then click the Word to Button
Button (the arrow above the Words list pointing to the Buttons List).
The word will be made into a button.  Note that the first occurance of the
word in the text will be made into a button.  If you add the word multiple
times, the first occurance will be made into a button, then the second, and
so on.	If a button isn't linked to a node when the file is saved, it won't
be written to the file.  Therefore you can make the second occurance of
a word into a button but not the first by adding the word two times, and only
linking the second button to the destination node.  See Linking buttons for
more information.

To delete a button, select the node which contains the button in the
left Nodes list.  Then select the button to delete in the Buttons list.
Then click the - button to the right of the Buttons list.  The button will
be deleted.

To link a button, select the node which contains the button in the left
Nodes list.  Then select the button to be linked in the Button list.
Then select the file that contains the node to link to in the Files List,
and finally, select the Node from that file to link to in the right Nodes
list.  The button is now linked.  You can change the node it is linked to
at any time by repeating the above process.

To unlink a button, select the node which contains the button in the left
Nodes list.  Then select the button to be unlinked in the Button list.
Then click on any file in the files list.  The existing link will be cleared,
and no new link will be established unless you also select a node in the
given file in the right Nodes list.

To save the selected guide, click the Save button.  If the guide already
has a filename it will be saved.  Otherwise, a file requester will prompt
you for a filename.  Note that if a guide links to guides that don't have
filenames (are called Untitled1, Untitled2, etc.) you will be prompted
for filenames for these guides also, and these guides will also be saved.
You can tell which file you are being prompted for a filename for by
looking in the title bar of the ASL file requester.  It will contain
the name of the file (Untitled1, Untitled2, etc.).

You save all open guides by clicking the Save All button.  You will be
prompted to enter filenames for all untitled guides.

To save the selected guide under a new filename, choose the Save As...
button.  Choosing this will bring up an ASL file requester allowing you
to specify a filename.	Once you change the filename of a file, it is
a good idea to click Save All.	When you do this, you will re-save all
open guides, some of which may link to the renamed guide.  When these
guides are re-saved, they will use the new filename instead of the old one.

To bring up the Prefs requester, click the Prefs button.  It looks like
the Workbench Prefs icon, a question mark in a box.  The Prefs requester
will then appear.

In the Prefs requester you specify the command line to run the Editor to
use to edit nodes, and its required stacksize.	By default, these are
MEmacs and a stacksize of 4096.  You may change these to anything you wish,
and then click either Save, which will make your changes permanent, or use,
in which case any changes will only be effective until you exit GuideGen.
You can also choose Cancel to abandon any changes you may have made.

Note that the format in which you specify the command line for the Editor
is similar to that of a C-style format string.	Somewhere in the string,
you should include "%s" (type the quotes too).  At this point, the filename
of the temporary file containing the Node text will be substituted into the
command line.  If you do not include this, your editor will not load the
file containing the node text and you will be unable to edit your nodes.

To quit, click the Quit button.  A requester will appear verifying that
you wish to quit.  If you answer yes, you will be immediately booted out
of GuideGen; you will not be prompted to save unsaved files.