@databse HelpSysDoc @node Introduction FASTREAD.GC DOCUMENTATION INTRODUCTION FastRead.gc is a gui which provides an easy method to access documentation either completely, in reader mode, or by fetching selected patches of text for online help from within a Gui4Cli user's own program. This gives the Gui4Cli user an easier and quicker way than AmigaGuide to write documentation about his program, and the same document can also be used for quick help from within the user's own program, although FastRead.gc can also do these things with AmigaGuide documents as well as its own, just as easily. FastRead.gc works in two modes. Firstly it is able to be used as a document reader, and secondly as quick help from within a program, fetching and displaying instructions on individual gadgets. It can do this because it has a separate reader gui, ViewText.g, which displays the text. FastRead.gc handles the preprocessing of documents and displays the index, so is not needed when only online help is required. ViewText.g handles this part. @endnode @node Requirements REQUIREMENTS The Gui4Cli help system needs no special support libraries or files, and only needs Gui4Cli installed on the system. The work is done by two binary files, GetNodes and WriteNode, which are a part of the Gui4Cli distribution. @endnode @node "Where Things Are" THE FASTREAD DIRECTORY TREE Until you are familiar enough with FastRead.gc and its associated programs to be able to take it and use it for your own purposes, you may find it helpful to know where things are in relation to your overall directory structure. You need Gui4Cli to be installed in your system, and it will use the directory GUIS: as its home base. Within that environment, FastRead.gc and its friends are located thus : GUIS: ;Home base for Gui4Cli | |___Docs ;Gui4Cli directory for documents. eg, | ;HelpSystem.txt (the file you are | ;reading now), plus any further docs, | ;guides, etc. which you collect or | ;create. | |___C ;Gui4Cli directory for binaries. GetNodes | ;and WriteNode are stored in here. | |___Tools ;Gui4Cli directory for global tools, such | ;as FastRead. | |___FastRead ;FastRead.gc, ViewText.g, HelpDemo.gc | ;and related icons. | |___Idx ;Directory to hold index files as ;created by FastRead.gc. @endnode @node "The GCHELP: Assign" THE GCHELP: ASSIGN For general convenience, the directory name GCHELP: is temporarily assigned to whatever directory holds FastRead.gc or any of its associated programs. The assignment is created by the FastRead.gc suite of programs when any of them start up, and is removed again when the programs end. The assign will have no effect on anything else you @endnode @node "Writing Your Docs" WRITING A DOCUMENT As with AmigaGuide, the doc file is written in any text editor. The difference is that unlike AmigaGuide, the Gui4Cli help system does not require the insertion of complex formatting codes. Only three codes are used - '@node' and '@endnode', to mark the start and end of various topics that the user wants to access, and a '@database' header. These are the same markers as AmigaGuide uses. FastRead.gc will strip out all other AmigaGuide formatting codes when reading AmigaGuide. Text colours and styles are not supported, since the handling of AmigaGuides by FastRead.gc is there merely to enable the user to write his docs in either format and still have access to online help. A document which is intended for access by FastRead.gc needs some preparatory editing. The file you are now reading has examples of such editing included. Each section of text which you want to appear in the index must begin with '@node' and end with '@endnode'. It's as simple as that. A short title must be placed after '@node'. This is the subject title which will appear in the FastRead lister. If the title contains spaces, enclose it in double quotes. The same applies to the database title. For the purposes of this text, let the | character represent the extreme left of your editing window. Then the layout of your document might look like this : |@database |@node Introduction | |(Introductory text) | |@endnode | |@node "Contacting the author" | |(Text about the author) | |@endnode The first line in a document must be a '@database' statement, and the last line an endnode statement. @endnode @node "The Index File" THE INDEX FILE When your document has been written, and FastRead.gc reads this or an AmigaGuide file for the first time, an index file will be created automatically, and stored in the 'GUIS:Tools/FastRead/Lst' drawer. The name of the index file will always be the same as the document it belongs to, with a '.idx' filename extension added. For example, if your document was called 'MyDoc.guide', the index file would be created with the name 'MyDoc.guide.idx'. The index file is used in the FastRead.gc lister, and it's contents will look something like this... Introduction 38 1047 Requirements 1114 245 The numbers are the start and length offsets of the subject text in bytes, so that FastRead.gc will know where to go to retrieve the text. These numbers are hidden in the lister, and are used also for online help within the users program. @endnode @node " Index Format" FORMATTING THE INDEX If your text naturally divides itself into major topics and subtopics, then subtopics can be indicated by preceding the node title with, say, three spaces, placed INSIDE the double quotes which enclose the node title, thus : |@node " Requirements" The exact number of spaces doesn't matter, but you must be consistent. You can indicate sub-subtopics in a similar way. The number of spaces must be more than the number used for the preceding level, and should be consistent... |@node Introduction |(text .. any number of lines) |@endnode |@node Applications |(text) |@endnode |@node " Application 1" |(text) |@endnode |@node " Refinements A" |(text) |@endnode |@node " Refinements B" |(text) |@endnode |@node " Application 2" |(text) |@endnode |@node Limitations |(text) |@endnode Note that the subject titles that do not need formatting, and only consist of one word, have no quotes enclosing them. It would do no harm to put these node titles in quotes, but would be pointless. The quotes MUST be there for the other titles in the above example. @endnode @node "The Programs" THE PROGRAMS FastRead.gc is the document reader itself, and can work in two modes. Stand alone, which will read a whole doc file, and Online, which fetches selected patches of text, or topics from the doc file. In Stand Alone mode, FastRead.gc does not need the user's program to be running, and becomes a text file reader. In Online mode, the commands to fetch text are sent from the user's program instead of FastRead.gc. ViewText.g is the part of FastRead that actually displays the text, and runs without FastRead.gc for online help, being controlled from the user's program. HelpDemo.gc is a 'mock up' of the user's program, intended to demonstrate how FastRead.gc is used from within a Gui4Cli script to obtain online help. @endnode @node " The Binaries" THE BINARIES GetNode: Usage: GetNodes <source doc> <.idx file> This is the program that creates the index file (.idx) for your documentation. GetNodes will grab all the node titles in your doc and calculate the starting byte and length of each one. The .idx file is laid out like this... --- Title --------------------------- Start & Length ----- Introduction 38 1047 Requirements 1114 245 WriteNode: Usage: WriteNode <document> <start> <length> WriteNode uses the start and length numbers in the .idx file generated by GetNodes to find and grab the required piece of text from your document. The piece of text is saved to Ram Disk:, and is always called 'Guide.txt'. @endnode @node " FastRead.gc" FASTREAD.GC This is the actual text reader. FastRead.gc opens two windows when in Stand Alone mode, the main window with a lister, containing the various topics and subtopics of the doc file, and the text window, which displays the actual text of the topic or subtopic. On loading, FastRead.gc presents a file requester from which the doc file to be read is chosen. After the file has been chosen, the lister will display the topics and subtopics. A new document can be loaded at any time via the 'Open' button. Clicking with the left mouse button on any topic or subtopic will bring the text window to the front and display the text. A right mouse button click brings the lister back to front, and clears the text window, ready for another topic to be selected. To Quit FastRead.gc, simply close either of the windows with their close gadget. A simple lister search facility is included. This consists of a string gadget at the top, with a button marked [ ] next to it. This can be useful for very large documents, or for AmigaGuides which contain hundreds of nodes. By typing any character string into the string gadget, the first index item which matches will move to the top of the lister. The search is not case sensitive. For example, the 'Requirements' index item can be found in a long list by typing 'req, REQ, or reQ' into the string gadget. Clicking on the button marked [ will move the next matching index item to the top of the lister. Pressing the HELP key whilst the FastRead.gc lister window is active will load and display this text. Any document being read at the time will be kept and not need to be reloaded. FastRead understands one icon tooltype - VTMACRO, which sets the default AmigaDOS or ARexx script to run when the [Macro] button is pressed in the ViewText window. @endnode @node " ViewText.g" VIEWTEXT.G This is the text window part of FastRead.gc, but is a global file which can be used by either FastRead.gc or the user's program, and is used without FastRead.gc for online help. All calls concerning online help are made from the users program. ViewText.g is initially loaded from there, and displays the specific text patch requested. See the section on HelpDemo.gc for more information. When the patch of text has been read, a click on the right mouse button closes ViewText.g. The ViewText.g window has a button strip along the top to the right, containing four buttons. These are described as follows... Macro - Opens a file requester and enables an AmigaDOS or ARexx script to be run. If the VTMACRO tooltype is set in FastRead's icon, this macro will run without opening the requester. Prev - This goes to the previous subject in the FastRead.gc lister and displays it. When displaying online help, this button is ghosted. Next - This goes to the next subject in the FastRead.gc lister and displays it. When displaying online help, this button is ghosted. Grab - Saves the piece of text currently being displayed in the ViewText.g listview. A file requester will appear for the save path and filename. This function is also accessible by pressing CTRL-S. Quit - This quits completely when used in stand alone mode, for reading complete documents. However, in online mode, the Quit button simply closes the Viewtext.g window. This function is also accessible by pressing CTRL-Q. @endnode @node " HelpDemo.gc" HELPDEMO.GC This is a 'mock up' used to simulate the user's program, and to demonstrate how to get selected patches of text from the program's doc file to use as online help. HelpDemo.gc can be read in any text editor or viewer. (Recommended) Borrowing parts of HelpDemo.gc for your own project =================================================== Loading ViewText.g - After 'xOnLoad' are the lines... extract fastread.gc guipath fre_path assign GCHELP: $fre_path delvar fre_path This grabs the path of HelpDemo.gc and makes a temporary assign. The full path of ViewText.g is GUIS:Tools/FastRead/ViewText.g, but the GCHELP: assign is used throughout for convenience. The next important line is... GuiLoad GCHELP:ViewText.g This loads ViewText.g without opening its window. Put a copy of that line in a similar position in your program. Specify your document - In the script of HelpDemo.gc you will find: ; ----- The target document is named here ---- docname = GUIS:Docs/HelpSystem.txt This puts the path and filename of the document into a variable called 'docname'. Include the same in your program, changing 'GUIS:Docs/HelpSystem.txt' to your document's path and filename. Switching help mode on and off is done in this case by a checkbox, but can be done by almost any gadget you like. Near the top of the script is the line... helpon = 0 which sets the helpmode to off. It will remain off until the checkbox is selected. The 'helpon' variable is used later to test whether help has been switched on or off. Assign topics to gadgets - Find the patch of script which contains ; ---- The button for the HelpDemo patch ---- This is where you will need the '.idx' file which belongs to your document. The index file is not actually used with online help, but the byte offset numbers that it contains are used to locate the text patch in your document. You will see the lines... offset = "8639 1992" gosub helpdemo.gc open The actual numbers are not important here, since they will be the ones in the .idx file belonging to your document. The first line puts the start and length offsets into a variable called offset. This variable is used later in the script by a subroutine called 'open', which does the biz. The second of the two lines jumps to the 'open' subroutine. At the bottom of the HelpDemo.gc script you will see the subroutine as follows... ; ---------- This is the routine for opening the reader gui... xroutine open if $helpon = 0 return elseif $helpon = 1 cli 'GUIS:C/WriteNode $docname $offset' guiopen viewtext.g guiwindow viewtext.g front lvuse viewtext.g 1 lvchange ram:guide.txt stop endif This subroutine is shared by all the gadgets that use online help. To go through it line by line... if $helpon = 0 return If the helpmode has not yet been activated, go back to the routine of the gadget that called the 'open' subroutine and carry out any commands remaining there. elseif $helpon = 1 cli 'GUIS:C/WriteNode $docname $offset' Alternatively, if the helpmode has been activated, run the WriteNode binary in GUIS:C, and send to it the document path and filename, and the offset (start and length) numbers. WriteNode will grab the required text from the document, and create a file in the Ram Disk: called 'Guide.txt' which contains the text. See the section on the binaries for more information. 1 guiopen viewtext.g 2 guiwindow viewtext.g front 3 lvuse viewtext.g 1 4 lvchange ram:guide.txt 5 stop 1 - Open the reader window. 2 - Bring it to the front. 3 - Select its listview as the current one. 4 - Import the file 'Ram Disk:Guide.txt' into the listview and display it. 5 - Halt all operation and wait for the user. Read the HelpDemo.gc script for more information. @endnode @node "Rogues' Gallery" AUTHORS The Gui4Cli Help System was written as a joint project between Graham Maddox of the UK and John Collett of New Zealand. Graham Maddox - The concept and all Gui4Cli scripts. <gmaddox@netcentral.co.uk> John Collett - Document format concept and most of the development. <jcollett@waikato.ac.nz> Dimitris C. Keletsekis - Kindly supplied the binary engines. <dck@hol.gr> @endnode