home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 10 / Fresh_Fish_10_2352.bin / fishdisks / d1001.lha / Programs / AmigaGuide / AG_V34 / Docs / AmigaGuide.txt < prev   
Text File  |  1993-03-25  |  34KB  |  1,212 lines
  1.  
  2.                             AmigaGuide TM
  3.                            David N. Junod
  4.  
  5.    (C) Copyright 1990-93 Commodore-Amiga, Inc.  All Rights Reserved
  6.  
  7.  
  8.                             INTRODUCTION
  9.  
  10.  
  11. The standard Amiga keyboard sports a HELP key, yet there has been no
  12. system provided support for this key.  Now, there is AmigaGuide,
  13. which provides a standard method of displaying help and other on-line
  14. documentation to the user.
  15.  
  16.  
  17.  
  18. Capabilities
  19.  
  20. AmigaGuide uses an Intuition window that contains a scroll bar,
  21. buttons and pull-down menus, to display plain ASCII text files or
  22. AmigaGuide databases.
  23.  
  24. An AmigaGuide database is a set of related documents contained in one
  25. file.  Each document may contain references to other documents, using
  26. what is called a link.  A document may contain any number of links,
  27. pointing to any number of other documents.  When the user selects a
  28. link, the document that the link points to will be displayed.  The
  29. user may then use the links to read through the database, following
  30. whatever path they may choose.  The technical term for AmigaGuide's
  31. abilities, is hypertext.
  32.  
  33. The user may at any time print a document or a portion of the
  34. document.  They may also send portions of a document to the
  35. clipboard, for use in other applications.
  36.  
  37. Using ARexx, the user may write scripts, or an application could
  38. provide scripts, to control AmigaGuide.
  39.  
  40. Cross-reference tables can be loaded that specify where a keyword, or
  41. phrase is defined.  The user can then use AmigaGuide's Find Document
  42. facility to quickly display a document based on keyword, without
  43. having to know the name of the database that it is located in.
  44.  
  45. AmigaGuide provides a unique feature to hypertext systems, called
  46. Dynamic Nodes.  A Dynamic Node is a hypertext or plain text document
  47. that is generated in real-time as opposed to coming from a static
  48. file.  An application that generates Dynamic Nodes is called a
  49. Dynamic Node Host.
  50.  
  51.  
  52.  
  53. Interfacing
  54.  
  55. AmigaGuide databases are accessed in three different ways:
  56.  
  57.  
  58.   o  Databases can be browsed directly from the Workbench or Shell
  59.      using a utility named AmigaGuide, a hypertext replacement for
  60.      More.
  61.  
  62.   o  AmigaGuide support can be added to an existing application, that
  63.      supports ARexx, by using AmigaGuide's ARexx function host
  64.      capabilities.
  65.  
  66.   o  Applications can use the functions of AmigaGuide to provide help
  67.      on gadgets, menus and windows.  For example, the user could
  68.      position the pointer over any gadget or menu item, press help,
  69.      and the appropriate document would be displayed in the
  70.      AmigaGuide window.  The application could also have AmigaGuide
  71.      display a pertinent portion of the current project.
  72.  
  73.  
  74.  
  75. Other Uses
  76.  
  77. In addition to help or on-line documentation, AmigaGuide has other
  78. possible uses.  For example,
  79.  
  80.  
  81.   Tutorials
  82.   An application that has an ARexx port and supports AmigaGuide could
  83.   set up a help system that not only provides help, but could also give
  84.   examples. The user could read about a feature, then click on the
  85.   EXAMPLE button, which would run an ARexx script that would give an
  86.   example of use.  For instances, to show Pattern Fill, the script
  87.   could draw a circle, select a pattern, and then fill the circle.
  88.  
  89.  
  90.   Computer Aided Instruction
  91.   The student could read about different topics, following links.  A
  92.   multiple choice quiz could be set up at the end where the questions
  93.   and answers run ARexx scripts to accumulate the score.
  94.  
  95.  
  96.   Program by Query
  97.   Many programmers develop using a Cut & Paste technique.  They
  98.   clip modules from the various applications or utilities that they
  99.   have written, and paste them together to build new applications.
  100.   A database could be set up of all these different code fragments
  101.   (such as loading and saving ILBM's, clipboard access, playing sounds,
  102.   etc.), you could step through, answering questions, while the sections
  103.   that you need are being appended to a new source file.
  104.  
  105.  
  106.  
  107.                USING AmigaGuide FROM WORKBENCH OR CLI
  108.  
  109.  
  110. A number of utilities are provided to access AmigaGuide databases
  111. from the Workbench or Shell.  These utilities are:
  112.  
  113.  
  114.   AmigaGuide
  115.   This tool is much like the system utility, More, but is also capable of
  116.   interpreting AmigaGuide databases.
  117.  
  118.   LoadXRef
  119.   Used to load a cross-reference from disk into memory.  Multiple
  120.   files can be loaded.
  121.  
  122.   ExpungeXRef
  123.   Used to clear the cross-reference table from memory.
  124.  
  125.  
  126. AmigaGuide
  127.  
  128. The AmigaGuide utility is used for browsing through AmigaGuide
  129. databases. It can be run from the Workbench or the Shell.
  130.  
  131. To use it from Workbench, set the default tool of an AmigaGuide
  132. database's icon to AmigaGuide.  Currently, the AmigaGuide utility
  133. doesn't recognize any tool type parameters.
  134.  
  135. From the Shell, AmigaGuide uses the following command template.
  136.  
  137.  
  138.   DataBase,Document/K,Line/N,PubScreen/K,PortName/K:
  139.  
  140.  
  141. The following are descriptions of the arguments.
  142.  
  143.  
  144.   DataBase
  145.   The name of the AmigaGuide database to display.
  146.  
  147.   AmigaGuide will look in the current directory for the database.  If the
  148.   database isn't found, then AmigaGuide will search through its path for
  149.   the database.  To set the path, see the Path paragraph in the USER
  150.   PREFERENCES section.
  151.  
  152.   Document
  153.   The document within the database to display.  AmigaGuide will use
  154.   the cross-reference table to automatically supply the DataBase and
  155.   Line parameters.
  156.  
  157.   Line
  158.   The line of the document to start displaying from.
  159.  
  160.   PubScreen
  161.   The public screen to open on.  Remember that public screen names are
  162.   case sensitive.
  163.  
  164.   PortName
  165.   The name to assign to the ARexx port for this occurence of AmigaGuide.
  166.  
  167.  
  168. LoadXRef
  169.  
  170. The LoadXRef utility can be used from Workbench or the Shell to load
  171. cross-reference files from disk into memory.  Multiple cross-
  172. reference files may be loaded at a time.
  173.  
  174. From Workbench, just set the default tool of a cross-reference file's
  175. project icon to LoadXRef.  This tool doesn't support any tool type
  176. parameters.
  177.  
  178. From the Shell, just specify the name of the cross-reference file to
  179. load.  LoadXRef will look in the current directory for the file.  If
  180. the file isn't found, then LoadXRef will search through the users
  181. preference path for the file.
  182.  
  183.  
  184. ExpungeXRef
  185.  
  186. The ExpungeXRef utility is used to remove all entries from the cross-
  187. reference table in memory.
  188.  
  189.  
  190.  
  191.                           USER PREFERENCES
  192.  
  193.  
  194. AmigaGuide allows a number of items to be tailored to the users'
  195. preference.  These preference items are stored in environment variables.
  196. The AmigaDOS command SetEnv can be used to set any of these variables.
  197.  
  198. In order to set any of the following environment variables, an
  199. ENV:AmigaGuide directory must be made.
  200.  
  201.   makedir ENV:AmigaGuide
  202.  
  203. A Preference Editor that sets the AmigaGuide preferences would write
  204. in the ENV:AmigaGuide directory when "Use is selected, and write in
  205. the ENVARC:AmigaGuide directory when "Save" is selected.
  206.  
  207. Following is a list of the variable names, and what they control.
  208.  
  209.  
  210. Path
  211.  
  212. This variable contains the list of directory names that AmigaGuide will
  213. search through when it attempts to open a database.  The directory names
  214. are separated by a space.
  215.  
  216.   For example:
  217.  
  218.     SetEnv AmigaGuide/Path "Workbench:Autodocs Workbench:Includes"
  219.  
  220.  
  221. Text
  222.  
  223. Used to specify the graphical style that the links are presented in.
  224. The possible styles are:
  225.  
  226.     BUTTON    Draw a raised border around the text (default).
  227.     UNDERLINE    Underline the text.
  228.     BOLD    Bold the text.
  229.     ITALIC    Italicize the text.
  230.  
  231.   For example:
  232.  
  233.     SetEnv AmigaGuide/Text BUTTON
  234.  
  235.  
  236. Pens
  237.  
  238. This variable provides the user with the ability to specify the
  239. colors to use for the various renderings that AmigaGuide performs.
  240.  
  241.     SetEnv AmigaGuide/Pens <abcdefgh>
  242.  
  243.   Where:
  244.  
  245.     a = Background pen
  246.     b = Button text pen
  247.     c = Button background pen
  248.     d = Highlighted button text pen
  249.     e = Highlighted button background pen
  250.     f = Outline pen
  251.     g = Highlight outline pen
  252.     h = Text on background pen
  253.  
  254.   For example:
  255.  
  256.     SetEnv AmigaGuide/Pens 21213001
  257.     SetEnv AmigaGuide/Text BOLD
  258.  
  259.  
  260. Internally, AmigaGuide subtracts '0' from the pen number, so values
  261. can range from 0 to 207.
  262.  
  263.  
  264.                    AUTHORING AmigaGuide DOCUMENTS
  265.  
  266.  
  267. Authoring an AmigaGuid