@database amosguide.guide
@author "Paul Hickman"
@$VER: AmosGuide.Gudie 1.02 (20.10.94)
@width 77
@index Index
@node main "AMOS Amiga Guide File Viewer Accessory"
@toc /main
@next _Introduction

		  @{u}@{b}Easylife Extension V1.10 - By Paul Hickman@{uu}

              @{u}AMOS AmigaGuide File reader / Help System  V1.01@{uu}

			E-Mail: ph@doc.ic.ac.uk@{ub}



@{u}Users Documentation@{uu}

	@{"Introduction              " link _Introduction}
	@{"Running The Program       " link _Running}
	@{"Basic Controls            " link _Controls}
	@{"Menu Options              " link _Menus}
	@{"Replacing AMOSPro Help    " link _ReplacingHelp}
        @{"The Docs Tree             " link _Tree}

@{u}Guide Authors Documentation@{uu}

	@{"Extra AMOS Links          " link _amos}
        @{"Directories As Nodes      " link _Directories}
	@{"Writing Extension Manuals " link _extensions}
	@{"Summary Of @ Commands     " link _commands}

@endnode




@node _Introduction "AmosGuide / Introduction"


                       @{b}@{u}AmosGuide.AMOS Introduction@{ub}@{uu}


    AmosGuide.AMOS  is a program for viewing any amigaguide database on
    an  AMOS  screen  which  is  styled to fit with the AMOSPro editor &
    Textreader  screens.   It is also a replacement for the AMOSPro Help
    facility,  as  the  AMOSPro  help files have been converted to amiga
    guide format, and are included in the Easylife docs drawer.

    All   features   of   amigaguide   files   documented  in  the  file
    AmigaGuide.Doc   (which   is   included   in  commodore's amigaguide
    distribution) are supported except:


  - Dynamic Nodes. (Rarely Used)

  - Close, Quit, System, RX & RXS links. (Close The Window / Run Rexx
    & DOS Programs)

  - Alink links are treated as normal links - I.E. The node is displayed
    in the same window - not a new one. Normally alink displays the node
    in a new window.


     
    The  following  additional  features  not  documented  by  commodore
    are also supported:

  - Bold, Italic & Underlined Text. (Also supported by Multiview)

  - @{"Amos" link _Amos} links. (Specific to this program) 

  - Viewing @{"Directory Listings" link _Directories} As Amigaguide pages. (Specific to this
    program)


    See @{"Command Summary" link _commands} for full details of supported features.
@endnode



@node _Running "AmosGuide / Running The Program"


                            @{b}@{u}Running The Program@{ub}@{uu}


The AmosGuide.AMOS program may be started in several ways:

  - Load it into the editor & Run it like any normal AMOS program.

  - Prun it from another AMOS program.

  - Run it as an accessory.

  - Run it from a user menu option.

  - @{"Replace the AMOS Help system with it." link _ReplaceHelp}


    If  you  Prun the program, or run it from the user/help menus, it is
    possible  to  set up the AMOS variable Command Line$ before running.
    If  you run it as a normal program or an accessory, the command line
    is always empty.  The following command lines can be used:



    HELP

	Display the main menu of the new Easylife / AMOSPro on-line help
        guide.



    HELP <NodeName>

	Display the given node of the AMOSPro on-line help guide. This
        is for compatability with the old AMOSPro help program, and keeps
	all the editor's help menu options working.



    KEYWORD

        When run as an accessory, or when it has replaced the AMOSPro
        help system, the command / function name beneath the cursor
        in the current editor window is read, and a help page for it
	is searched for in the AMOSPRo help file, @{b} and in all
        extension help files@{ub}. If it is not found the best
        approximation is shown, or the contents page of AMOSPro help.



    BANK <Number>

	The amigaguide database to read is taken from a memory bank of
        the previous program instead of a file. The "main" node is 
	displayed. This lets you write programs that provide help using
	Amos guide.



    BANK <Number> <NodeName>

	The amigaguide database to read is taken from a memory bank of
        the previous program. The named node is displayed.



    BANK <Number> <NodeName> <Path>

	The amigaguide database to read is taken from a memory bank of
        the previous program. The named node is displayed. <Path> is
	prepended to any links in the bank database which are to an
        external .guide file, but do not specify a full path. These
        links would normally be paths relative to the directory of the
        guide file being displayed. E.g.

	    \@{"A Link" link ADir/Fred.Guide/ANodeName}

        Will be linked to <Path>ADir/Fred.Guide/ANodeName


	    \@{"A Link" link HELP:Fred.Guide/ANodeName}

	Will not be affected as a full path is specified.


	NOTE: <Path> should end in a trailing "/" or ":"



    <FileName>

	The amigaguide database to read is taken from the named file.
	The "main" node is displayed.


    <FileName> <NodeName>

	The amigaguide database to read is taken from the named file.
	The named node is displayed.


    <DirectoryName>

        The named directory is displayed as a node.


    NOTE: Any argument may be quoted with double quotes E.g. If it 
          contains spaces.



If no Command Line$ argument is given, a fileselector appears to choose
a amigaguide database file / directory to read.
    
@endnode



@node _Controls "AmosGuide / Basic Controls"


                              @{b}@{u}Basic Controls@{ub}@{uu}


    The controls are exactly the same as multiview / amigaguide:


    - @{b}Arrows@{ub} & @{b}scrollbars@{ub} move arround the current page if it is all
      visible.

    - The @{b}Contents@{ub} button displays the contents page associated with
      the current page. For directory listings this will be the
      parent directory.

    - The @{b}Index@{ub} button displays the index page assoiciated with the
      current database (.Guide file)

    - The @{b}Browse@{ub} buttons move to the previous / next page of the 
      database.

    - The @{b}Help@{ub} displays the current nodes help page.

    - The @{b}[X]@{ub} button in the top left hand corner quits the program.

@endnode







@node _Menus "AmosGuide / Menu Options"

                               @{b}@{u}Menu Options@{ub}@{uu}


    @{b}Open...@{ub}

        This opens a file selector from which you can choose a new 
        database to display, or a directory to display are an amigaguide
        page. To may return to the previous database using the @{"Retrace" link _controls} 
        button.


    
    @{b}Command...@{ub}

        A String requester appears into which you may type the name of
        an AMOSPro / Extension command to try to find a help page for.
        To return to the previous database, use the @{"Retrace" link _controls} button.



    @{b}Turbocharge@{ub}

        When this program first reads a database from a file, there is a
        delay while the name & position in the file of each node is found.
        With large files, this may become quite significant (E.g. On my 
        A1200 the 330K AMOSPro help guide takes over a minute). Once a 
        database is loaded, turbochagring it will create a seperate file 
        containing this information (Which has the same name as the guide 
        with '.tbo' appended).

        Whenever a new database is opened, if a '.tbo' file exists, the
        node information is loaded from this file which is much faster.
        (AMOSPro help is then only 2 seconds). I strongly recommend using
        the turbocharger on AMOSPro_Help, and extension help guides.


        @{b}IMPORTANT@{ub}

        If you change the amigaguide file, you must delete the .tbo file,
        as the positions of the nodes may have changed.



    @{b}Print@{ub}

        Sends the current node to the default printer.



    @{b}About AmosGuide@{ub}

        Displays the Amos Guide information page.

   

    @{b}About Database@{ub}

        Displats some statistics about the currenlty loaded amigaguide
        file.



    @{b}Quit@{ub}

        I'll give you three guesses.

@endnode



@node _ReplaceHelp "AmosGuide / Replacing The Help System"


                      @{b}@{u}Why Should I Replace The Help?@{ub}@{uu}


    @{b}Advantages:@{ub}

  - The amigaguide help file can be easily edited to include extra
    information / bug reports, and is easier to write.

  - The rest of the universe uses amiga guide format - why should
    AMOS be different?

  - Help for extensions / accessories is automatically added by
    copying the appropriate guide into the help directory.

  - Both vertical & Horizontal scrolling of the page is possible.

  - You can delete the help files from your AMOSPro_Accessories
    disk, which means there is enough room to copy the easylife
    accessories there.

  - When you press the help key over a command to get help on it,
    extension commands will also be recognised (NOTE: This currently
    applies to the easylife & intuition extensions. Other extension
    writters should read the @{"Extension Manuals" link _extensions} 
    section).

  - It is easier to navigate through a database with Amos Guide than
    Amos Pro Help.



    @{b}Disadvantages:@{ub}

  - The viewer program is larger and a bit slower.




                         @{b}@{u}How Do I Replace The Help@{ub}@{uu}

    It is actually suprisingly easy. Select the 'Set Program To Menu'
    option of the AMOSPro editor, then select the top item of the
    Help menu. Press 'Replace' in the confirmation requester.

    When the file selector appears, choose the AmosGuide.AMOS program,
    and set the options as follows:


    Command Line$ = "KEYWORD"
 
    [F1] Run as hidden Program		<On>

    [F2] Load into current Window       <Off>

    [F3] Keep After Running             <On/Off> (How much memory do
						  you have?)


    Now save the default editor configuration. This will change the
    entire Help menu to using the AmosGuide viewer. 



                         @{b}@{u}Using The New Help System@{ub}@{uu}

    The entire AMOSPro help menu still functions exactly as it did
    before except the first item "Help" which is also bound to the
    help key now:

    - Searches for the keyword beneath the cursor in both the AmosPro
      help files, and all extension manuals. 

@endnode








@node _Tree "AmosGuide / The Docs Tree"

                               @{b}@{u}The Docs Tree@{ub}@{uu}


        The Easylife documentation is contained in a drawer Docs, 
        which should be added to the HELP: Assignment. I recommend
        that you copy any other AMOS related amigaguide files into
        this tree, if you have a harddisk. In particular, put an
        AMOSPro extension instrucion manuals into the extensions
        directory. This will allow them to be searched for help
        on particular commands when you press help from the editor.

        Feel free to add extra directories - Amos Guide generates
        the hypertext pages from the directory listing.
@endnode





@node _Amos "AmosGuide / AMOS Links"


                                @{b}@{u}AMOS Links@{ub}@{uu}


    This Amigaguide viewer recognises an extra type of link - to load
    an AMOS program into the editor. This feature is used extensively
    by the AMOSPro On-Line help to load the example programs. The 
    format of such a link is:


	\@{<label> amos <program>}

    E.g.

    	\@{"Edit Bobs" amos AMOSPro_Accessories:Object_Editor.AMOS}
   

   When the user clicks on such a link, the program is loaded into a
   new window of the AMOSPro editor, and the guide viewer program
   ends.

   NOTE: Clicking on such a link from other viewers E.g. Multiview will 
         have no effect. 


   NOTE: This isn't official amigaguide syntax - I made it up :-)
@endnode



@node _Directories "AmosGuide / Directory Listing Nodes"


                            @{b}@{u}Directory Listing Nodes@{ub}@{uu}


When you pass this program a directory name instead of a file name,
or you select a link which is to a directory, the directory is searched
for a file in that directory named ".GuideHeader". This may contain one
of 2 things:


1) A single line containing the name of a real amigaguide file to load
   instead of producing a directory listing.


2) A header for a directory listing. The header format is the same as 
   that of a normal amigaguide node, except:

   - There is no @endnode statement at the end of the file.
 
   - Links may only be to other files. 

   - The @node statement must be on the first line of the file.

   - The @toc,@next and @prev commands may not be used.


If no .GuideHeader is present in the directory a default header is
generated by the viewer. A listing of the directory is then appended
to the end of the header (However it was created), listing all the
sub-directory names, and all ".Guide" files. This node is then displayed
as a one node database. 


This mechanism is used to build the new AMOSPro on-line help system. The
Other help files menu is just a directory listing of the "Docs/" directory, 
which has a ".GuideHeader" file containing the title at the top of the page.

The "Docs/Extensions" directory is similarly structured, but the directory
"Docs/Extensions/Easylife" has a header file which contains the single
line "Easylife.Guide" which means that when that directory is selected from
the page above, Easylife.Guide is immediately loaded.

NOTE: When creating links to a directory listing, always use the node
      name "main".

@endnode




@node _extensions "AmosGuide / Writing Extension Manuals"

                         @{b}@{u}Writing Extension Manuals@{ub}@{uu}


    An extension manual is treated like any other file. The only difference
    is that it must be possible for AmosGuide to find the help page for a
    particular command for when the user presses the help key while the
    cursor is over an extension command. This is done by:

    - Giving any node which gives help on a command a node name which
      consists of "C_" followed by the command name without any spaces 
      e.g. The node describing "Fred The Command$" would be called
      "C_FredTheCommand$". 


    - If a node describes 2 or more commands, just beneath the node
      description include AKA lines for the other commands -E.g.

	NODE ElfAsc
	AKA ElfChar
	AKA ElfNotAsc
	AKA ElfNotChar

      AKA is not standard amigaguide syntax, so it will be ignored by
      other viewers.


    - I recommend use of the section layout used in Easylife.Guide for 
      each node that describes commands -  Command Syntax, Description,
      Notes, Errors and See Also.


    - Instruct the user to copy the extension guide to the extensions
      directory on this documentation tree. (Or write an installer script
      to do it for them).
@endnode


@node _commands "AmosGuide / Summary of @ Commands"

                                @{b}@{u}Command Summary@{ub}@{uu}


        @{"Global Commands   " link _com_glob} Affect the whole file
        @{"Node Commands     " link _com_node} Affect one node
        @{"Attribute Commands" link _com_attr} Affect some text
        @{"Link Commands     " link _com_link} Create a hypertext link


        NOTE: Some of these commands were added to the amigaguide
        syntax in V39 (KS3.0) and V40 (KS3.1) operating systems.
        The version shown in brackets alongside some command names
        gives the minimum version of amigaguide.library (Which Amos
        Guide does not use) needed to use the command. Most V40
        commands are not supported by Amos Guide yet.


        For more information on the purpose & syntax of amigaguide
        commands, see "The Amigaguide Manual" by Aric R Caley.
        (E-Mail: dances@qedbbs.com) which is on aminet.
@endnode

@node _com_glob "Amos Guide / Summary of global Commands"    

                              @{b}@{u}Global Commands@{ub}@{uu}


    These commands appear outside of all nodes, usually at the top
    of the .guide file. (Except NODE and ENDNODE). An \@ sign should
    be placed before each command.

    Command:    NODE <name> <title>
    Effect:     Defines the start of a node & optional title.


    Command:    ENDNODE 
    Effect:     Defines the end of a node.


    Command:    INDEX <path/node>
    Effect:     Defines the location of the index page for this database.


    Command:    DATABASE <name>
    Effect:     Defines the name of the database held within this file.


    Commands:   $VER: <AmigaDOS version string>
                (C) <Copyright String>
                AUTHOR <name>
                HEIGHT <rows>
                MASTER <path>
                REM <remark>
                REMARK <remark>
                WIDTH <columns>

    Effect:     All Ignored By Amos Guide, as they serve no useful
                purpose for a viewer program.


    Commands:   DNODE   <name>
                FONT    <name> <size>
                HELP    <path/node>
                MACRO   <name> <commands>     (V40)
                ONCLOSE <rxcommand>           (V40)
                ONOPEN  <rxcommand>           (V40)
                SMARTWRAP                     (V40)
                TAB     <num>                 (V40)
                WORDWRAP                      (V39)

    Effect:     All Ignored By Amos Guide, although they are useful.
                Some of these may be implemented in the future.
@endnode

@node _com_node "Amos Guide / Summary of Node Commands"
    
                               @{b}@{u}Node Commands@{ub}@{uu}


    These commands only affect the node in which they occur. Again,
    an \@ sign should preceed each command.


    Command:    NEXT  <path/node>
    Effect:     Defines the node displayed when Browse >> is pressed.


    Command:    PREV  <path/node>
    Effect:     Defines the node displayed when Browse << is pressed.


    Command:    TITLE <title>
    Effect:     Defines the string show in the titlebar when the node is
                displayed. This can also be defined from the NODE command.


    Command:    TOC   <path/node>
    Effect:     Defines the node displayed when Contents is pressed.


    Command:    FONT     <name> <size>
                HELP     <path/node>
                INDEX    <path/node>
                KEYWORDS <keywords>           (Not Used Yet!)
                MACRO    <name> <commands>    (V40)
                ONCLOSE  <rxcommand>          (V40)
                ONOPEN   <rxcommand>          (V40)
                SMARTWRAP                     (V40)
                TAB      <num>                (V40)
                WORDWRAP                      (V39)

    Effect:     All ignored by Amos Guide. Note INDEX is supported
                at the global level, but not at the local level.


    Command:    AKA    <name>
    Effect:     This is an extra AmosGuide command, and will be ignored
                by other viewers. The AKA command specifies additional
                commands that are described on this help page, and is 
                used to create @{"Extension Manuals" link _extensions} with several commands
                described on the same page.
@endnode

@node _com_attr "Summary of Attribute Commands"

                            @{b}@{u}Attribute Commands@{ub}@{uu}


    These may appear anywhere in the main body text of a node, and
    modify the way in which part of the text is displayed.


    Command:    \@{b}                           (V39)
    Effect:     Turn on Boldface


    Command:    \@{ub}                          (V39)
    Effect:     Turn off Boldface


    Command:    \@{i}                           (V39)
    Effect:     Turn on Italic


    Command:    \@{ui}                          (V39)
    Effect:     Turn off Italic


    Command:    \@{u}                           (V39)
    Effect:     Turn on Underline


    Command:    \@{uu}                          (V39)
    Effect:     Turn off Underline


    Command:    \@{AMIGAGUIDE}                  (V40)
                \@{APEN <n>}                    (V40)
                \@{BG <colour>}                 (V40)
                \@{BPEN <n>}                    (V40)
                \@{PLAIN}                       (V40)
                \@{TAB}                         (V40)

    Effect:     Currently Ignored.


    Command:    \@{BODY}                        (V40)
                \@{CLEARTABS}                   (V40)
                \@{CODE}                        (V40)
                \@{FG <colour>}                 (V40)
                \@{JCENTER}                     (V40)
                \@{JLEFT}                       (V40)
                \@{JRIGHT}                      (V40)
                \@{LINDENT <n>}                 (V40)
                \@{LINE}                        (V40)
                \@{PAR}                         (V40)
                \@{PARD}                        (V40)
                \@{PARI <n>}                    (V40)
                \@{SETTABS <n> <n> ... <n>}     (V40)

    Effect:     Currently Ignored. These commands are part of V40
                amigaguide's formatting system. Text written to use
                them should also be formatted correctly if these
                commands are ignored.
@endnode

@node _com_link "Summary Of Link Commands"

                               @{b}@{u}Link Commands@{ub}@{uu}


    These commands may appear in the main body of a nodes text, and
    define a hyperlink. The general syntax is:

	\@{"<Label>" <command> <arguments>}

    Where <label> is the string that appears on the button to press. It
    cannot contain any attribute commands.


    Command: 	LINK
    Arguments: 	node to link to
    Effect: 	When the link is selected, a new node is displayed. The 
            	argument is the name of this node, or the path of the
		.guide file the node is contained in, followed by a '/',
		then the node name. The path may be relative to the
		current file. Amos guide also allows a @{"directory name" link _directories}
		to be used as the arguement, provided the node name given
		is '/main'.


    Command:	ALINK
    Arguments:	Same as link.
    Effect:	Officially supposed to be the same as link, but the new
		node appears in a new window. However multiview displays
		the node in the same window, making ALINK the same as LINK.
		Amos guide also does this.


    Comamnd:	CLOSE				(Pre V39 only)
		RX
		RXS
		SYSTEM
		QUIT				(Pre V39 only)

    Effect:     All Ignored By Amos Guide


    Command:    @{"AMOS" link _AMOS}
    Arguments:  Path of an AMOS Program.
    Effect:     Amos Guide Quits, and the program is loaded into the
                AMOSPro editor in a new window. Unsuprisingly, this is
                not offical amigaguide syntax, and all other viewers
                will ignore it.
@endnode