Simtel MSDOS 1992 June

home *** CD-ROM | disk | FTP | other *** search

/ Simtel MSDOS 1992 June / SIMTEL_0692.cdr / msdos / hypertxt / hs25.arc / HSDEV.LZH / HSAUTH.DOC < prev next >

Wrap

Text File | 1989-05-08 | 66KB | 2,378 lines

HyperShell Hypertext control system Version 2.5 Authoring Guide Copyright (c) 1989 Text Technology Text Technology 66 Kennedy Avenue Macclesfield Cheshire England SK10 3DE - 1 - Chapter 1 Introduction 1.1 Introduction This manual is a guide to the production of hypertext files for the HyperShell system. It describes the mechanism for producing and maintaining simple hyperfiles, and provides an introduction to more advanced programming using HyperShell. It is recommended that the reader becomes familiar with the operation of HyperShell, by reading the Users guide and by using HyperShell, before reading this document. An understanding of the fundamentals of MSDOS is also useful. The full specification of HyperShell files, and full details of the operation of the editor and support utilities are described in the Reference Guide. The hypertext concept and the HyperShell product are described in the Shareware notice document. 1.2 Authoring Creating Hypertext documents is known as 'authoring'. The process of creating an effective Hypertext document is similar to producing a reference book, although the structure is very different. A great deal of planning is necessary before a hyperfile is created, as the information has to be broken down into units called 'frames', and links created to bind these frames together. HyperShell files, known as 'hyperfiles', consist of the text to be read by the 'user', and control information. In its simplest form, a HyperShell document has to be split into 'frames' of a certain size and each frame needs to be identified. Some means - 2 - HyperShell Introduction Authoring Guide of moving from a frame to related frames is also necessary, even if it is just to permit stepping through the frames sequentially. HyperShell provides some standard commands to provide selection from a table of contents, searching for a string etc. The real power of Hypertext, however, is provided by embedded references in the text to other frames or sources of information. HyperShell provides these in a straightforward and powerful way, and also provides popup menus and paged displays, as well as a whole range of generic actions. The creation of the hyperfile can be done using a simple text editor or word processor, or can be done using the HyperShell authoring tools. The tutorial will assume the use of the HyperShell editor. 1-3 Version 2.5 HyperShell Tutorial Authoring Guide Chapter 2 Tutorial 2.1 File contents A hyperfile is a simple text file, in that it contains lines of text which can be viewed or edited with conventional text handling utilities such as text editors. The hyperfile contains identification and formatting details of the frames and other items in the file. It is made up of items general to the hyperfile, and items relating to each frame in the hyperfile. Note that the order of certain items is critical for the correct operation of the hyperfile, but in most cases HyperShell takes a rather relaxed attitude towards minor misdemeanors and will not complain if it finds things it wasn't expecting. This may mean, however, that you can make mistakes and that these will not be immediately obvious when you run HyperShell. The checking utility is provided to assist with the detection of errors and of unresolved cross references. 2.2 Tutorial 2.2.1 Simple hypertext The most simple hyperfile contains a number of small blocks of text held in frames. A frame is the unit of presentation, being the set of information presented at one time. The frames usually hold information about one subject, and the name of the subject usually forms the name of the frame. To produce a hyperfile, we can use the HyperShell editor. To invoke the editor, make sure you have the program HE.EXE available to run, and that you have sufficient space on the default drive and directory to store the resulting file (about 40k). For the example, we will create a hyperfile about cars, called CAR.HYP. To create this, type:- 2-4 Version 2.5 HyperShell Tutorial Authoring Guide A> he -c car The editor will create a file with one frame in it called 'introduction', and will display that frame. To change the name and title of this frame, we just press Shift-F5. At the bottom of the screen, the editor will ask for the new name and then the new title. We can call the frame 'the car' and give it a title of 'all about cars'. After changing the details the new name and title will be displayed at the top of the frame display. We can now enter some text for the frame. Pressing F4 will cause the editor to enter edit mode on the current frame. In edit mode, you can type in text just as with a word processor or text editor. You can move around the text using the cursor keys, delete text using the delete keys, and enter new text at any point just by typing. If you now enter the following text, you can see how this works (don't worry if the text isn't in the exact format). If you get in a mess, you can always exit from the editor, delete the file, and start over. The car is a very important item in our everyday life, yet we do not think about what is going on inside the engine of the car, or of how the brakes make the car stop. The bodywork of a car does more than keep the rain out, and the electric system provides much more than is at first apparent. When you have completed this, you can exit the edit mode by pressing F10. The text will appear along with the name and title in the frame display. We now need to create further frames about the engine etc. To add a frame, press Shift-F1, then supply the frame name and title. Do this now, supplying the name 'engine' and title 'the power plant'. After you have done this, the editor automatically puts you into edit mode to enter the text for the frame. Enter the following text:- The engine provides the central power unit for the car. It powers the wheels to move the car along. It generates electricity for the battery and the electric system. It provides heat to keep the windscreen clear of condensation, and to keep you warm. The engine runs on some form of fuel. After you have entered this, type F10 to exit. Use the same mechanism to enter the following frames:- name 'electric system' title 'electrical components' 2-5 Version 2.5 HyperShell Tutorial Authoring Guide The electric system of the car provides a number of essential services. The battery is used to store electricity for starting the car, and to act as a reservoir for when a heavy load is placed on the electric system. The ignition system is used to provide the sparks to ignite the fuel in the engine. The lighting system provides lights for indicating, warning, and night driving. The in car entertainment system is used to stop you from getting bored on long trips. name 'bodywork' title 'the shell of the car' The bodywork of the car provides the main structure which holds together the components of the car. It provides a secure and weatherproof compartment for you to travel in, and gives you something to polish in the summer and worry about in the winter. name 'brakes' title 'the braking system' The braking system of the car provides the means of stopping the car. Brakes on a car need two independant systems for braking, so that one system can act as a backup if the other one fails. Normally, there is a hydraulic footbrake system and a cable operated handbrake, although some cars have hydraulic handbrakes. name 'ignition system' title 'to ignite the fuel' The ignition system provides a spark to ignite the fuel vapour drawn into the cylinders through the carburettor. The spark is timed to ignite the fuel just before the piston gets to the top of its stroke, so that the energy will peak during the downward stroke. A distributor directs the spark from the coil to the correct sparking plug. When you have done this, you have a very simple hyperfile set up. To provide some cross-references, the autoreference action can be performed on each frame. To select each frame in turn, select the contents list from the frame display control menu (or press F2), then select the frame from the list by pressing the letter in brackets at the left, or by using the mouse or TAB key to select the frame reference. This should put you in frame 2-6 Version 2.5 HyperShell Tutorial Authoring Guide display mode for the frame selected. If you select the first frame ('the car'), you can then press F4 to enter edit mode on that frame. When in edit mode, you can press SHIFT F9 which causes reference flags to be added to the frame text. You can now press F10 to exit the edit mode for that frame and select the next one from the contents list. When you have finished doing this to all the frames, you should be able to navigate around the frames by selecting the highlighted references. It is normally best to do the autoreferencing after you have added all frames and other items to the hyperfile. When you do this on your own files, you may see certain references highlighted that are not what you expected, and are meaningless in the context in which they occur. To remove unwanted references whilst still in edit mode, simply position the text cursor over the reference and press CTRL F3. Now that you have set up your hyperfile, you can exit the editor by pressing F10. You may now run the browser against it by typing:- hs car You can now see your first hyperfile in action. You can see that it is fairly easy to set up a simple hyperfile, but you will want to improve the appearance of the display, and to offer more supporting information in many cases, so we will progress the hyperfile. 2.2.2 Adding features Suppose you want to add your own special heading to appear on each frame of the hyperfile. This is easier than you may imagine. Reenter the editor now, so we can add some more items to the hyperfile. he car As we want to add a header section, we will need to select the global item list by pressing F5 from the frame display. You will see that at the start of the list is a .REMARK item. We will add the header after this. To do this, select the .REMARK item by pressing the letter to the left of it, or by selecting the reference. A menu will now popup, and you should select INSERT NEW ITEM AFTER. This will in turn pop up a menu asking what type of item you want to insert - select the HEADER option. You will now be prompted for the name of the item you wish to copy text from. You may just press RETURN here to not copy any text. To enter the text for the header, you need to 2-7 Version 2.5 HyperShell Tutorial Authoring Guide select the HEADER item, and take the EDIT ITEM option on the menu. You will now be put into edit mode on the HEADER section, and should enter the following text:- [$1] [$2] All about cars [$4] [$5] This sets up the header to contain the frame name and title, a general heading and the date and time. When you have done this, you can press F10 to exit the edit mode. This will return you to the global item list. If you now select the HEADER item again, only this time select INSERT NEW ITEM AFTER, and choose FOOTER from the item type menu. Again press RETURN when the request for copied item prompt appears. Then select the FOOTER item and take the EDIT ITEM option on the menu. This will enter edit mode for the FOOTER. Enter the following text, this time watching the display line at the bottom to see what is being entered:- ~L20 ~MTerms~E This sets up a footer section at line 20 which will give a menu of terms used in the hyperfile, each explained by a popup note. Then exit from edit mode by pressing F10. You now want to add a global menu item, which can be done by selecting the FOOTER item, and then taking the INSERT NEW ITEM AFTER option. Select MENU from the item menu, and enter 'Terms' as the name of the menu. Press RETURN for the copy from item prompt again. Then select the 'Terms' reference and take the EDIT ITEM option. Enter the following text:- Carburettor |NCarburettor Fuel |NFuel Spark |NSpark This sets up the menu of terms, with a note reference for each term. Exit from the edit mode by pressing F10. You now need to add the three notes. Do each in turn by following the example as for the 'Terms' menu, adding each note after the menu or after the previous note, and enter the following note texts:- name 'Carburettor' A carburettor is a device which is used to mix air with fuel. 2-8 Version 2.5 HyperShell Tutorial Authoring Guide The air is drawn in by the piston descending on alternative strokes. The air is first filtered through an air filter. The fuel is kept at a certain level in a float chamber next to the carburettor, and is sucked into the air stream. name 'Fuel' Fuel is the liquid or gas used in the engine to produce the energy. When the fuel vapour ignites, the gas expands and pushes the piston down. The mixture is generally ignited by a spark from a spark plug fed from an ignition coil. name 'spark' A spark is caused by the discharge of a high electric voltage across a gap. The voltage is generated by a coil with two windings, one a low voltage winding connected to the battery, and interrupted by the contact breaker and the other a high voltage winding connected through the distributor to the spark plug. After you have done this, press ESC to return to the frame display. The menu and notes provide additional material in support of the main frames. Note that these global notes should be kept together, as should global menus and scripts. You can add the note references to the frames by using the autoreference facility again, as you did to begin with, for all frames and notes. Whilst you are in edit mode for the 'ignition system' frame, try positioning the cursor on the word 'distributor', then press SHIFT F4. This will flag the word as a local note. When you have done this you can exit the editor and try out the hyperfile with HyperShell. You will note that when you select the 'distributor' reference, a message is issued saying that the item is not available. If you try running the checker program, it will check all the references and tell you what is wrong:- hc car 2-9 Version 2.5 HyperShell Tutorial Authoring Guide You should now reenter the editor and use the contents list to select the 'ignition system' frame. When you have selected this, press SHIFT F2. This will prompt for a note name, and you should enter 'distributor'. It will then enter edit mode and you can enter the following text:- The distributor is used to direct the high voltage current from the coil to one of the spark plugs. It also contains the low voltage contact breaker points, which determine when the sparks are produced. When you have done this, press F10 to exit edit mode, and again to save the file and exit the editor. Try out the hyperfile again, and the distributor note should popup when selected. This note is available only from this one frame, and is known as a 'local' note. A note with the same name can exist for another frame, but will be a different note, local to that frame. With the knowledge you now have, you can set up your own complex hyperfiles. You may like to extend the car hyperfile, and play around with adding further notes and menus, and modifying the header and footer texts. 2.2.3 Adding further features The straightforward hyperfile design described above, along with the HyperShell browser, provides a full traditional hypertext system. Additional features specific to HyperShell can be added to enhance the operation of a hypertext document. Some of these are described in this section. 2.2.3.1 Help A simple help facility is probably the first feature you will want to add to your system. The '?' key is used to attempt to invoke a global menu called 'help', which should only contain global note actions. This may be used for a simple help system. Note that this form of help is available from the paged display screen as well. The help system may be used to describe the operation of HyperShell and any specific operational aspects of the hyperfile, or can be used in support of the main 2-10 Version 2.5 HyperShell Tutorial Authoring Guide hyperfile material. The 'car' hyperfile could have a simple system describing how to use HyperShell to navigate around. To add such a system to the car hyperfile, insert a global menu called 'help' containing the following text:- Selecting |NSelecting Control keys |NControl keys and some global notes as follows:- Note name 'Selecting' containing:- You can follow references to move between frames and to display popup notes and menus. To select a reference position the mouse cursor using the mouse, cursor keys or TAB and SHIFT/TAB, then select by pressing ENTER, or the LEFT mouse button. and the note 'Control keys' containing:- You can use the function keys to control the system. The function keys are setup as follows:- F1 - Go to introductory frame F2 - Display contents of file F3 - Move back to previous reference F4 - Move back a number of steps F5 - Display list of noted frame F6 - Search file for text string F7 - Display contents of text file F8 - Perform requested action F9 - Temporary exit to DOS F10 - Quit to DOS This provides a fairly simple help system. To provide further features in a help system, the F1 key can be mapped to provide the help menu. More complex interaction with the help system is then possible, and the help menu is not limited to simple note references. To do this, you will need to create a SETUP script. This is simply a global script with the name 'SETUP'. 2-11 Version 2.5 HyperShell Tutorial Authoring Guide This should contain the following lines:- KF1MHelp MF1Help The first of these lines maps the F1 key to the global menu 'Help'. Note that frame,note,menu and script names are not sensitive to whether the name is in uppercase or lowercase or mixed case, and references can use cases different to the item names. The second line changes the text of the control menu for the F1 action to be 'Help', rather than the default of 'Home Frame'. The SETUP script is run whenever the hyperfile is 'entered' which is usually on startup when running HyperShell against the file. It will also be executed if you select a reference to this hyperfile from another hyperfile. It can therefore be used to set up any key mappings, colour schemes, options etc. required by a hyperfile. 2.2.3.2 Narrative flow Someone reading the hyperfile will normally follow a sequence of frames, and only divert to references when required. To provide a means of stepping through the frames of information, you can add a 'next frame' reference to the FOOTER text. To do this in the car hyperfile, edit the FOOTER frame text to the following:- ~L20 ~MTerms~E ~APress space bar to continue~PF+~K ~E This will provide a selectable action in the footer of each page which will cause the next frame to be displayed. It also maps the space key (or bar) to this reference ('~K ' does this), to enable the user to simply step through. Note that this type of frame reference (F+) will keep a backtrack list to allow the user to step back through the frames. It is also possible to step through so that no backtrack information is retained. This is done using the lowercase form of the reference (f+) in place of the other. 2-12 Version 2.5 HyperShell Tutorial Authoring Guide 2.2.3.3 Supporting files Normal text files, and files with just reference flags in them, can be used in support of the hyperfile in two ways. The F7 key allows a filename to be entered, and effectively issues a 'T' action to display the file a page at a time. The 'T' action can also be called from a reference in the text, as can any action. This reference takes the form e.g. ~ACar manual~PTmanual.txt~E The text 'Car manual' will appear as a highlighted reference in the text, and when selected will cause the file 'manual.txt' to be typed. This file may contain embedded references to the frames in the car hyperfile. One way to achieve this is to do it automatically when typing the file, rather than having to actually modify the file. This is known as autoreferencing, and is similar to the autoreference feature we met in the editor. To enable this, the line:- O41 would be added to the SETUP script (this starts with the LETTER O, not the figure 0). When this is done, a reference in the manual.txt file to 'bodywork' or 'brakes' would be highlighted when the file was typed, and could be selected, whereupon the relevant frame would be displayed. This feature permits the file viewing to be continued by simply issuing the action 'T' without a file name parameter. This action is provided by the F7 key. Another way that text files may be used in support of a hyperfile is the 'file note'. A reference of the form:- ~tradios~E refers to a file called 'radios.nte' which is displayed as a popup note when the reference is selected. You can try this out in the car hyperfile, by inserting the above reference in the electric system frame, and by providing a simple text file with the correct name. Note that the extension '.NTE' is added only if one is not supplied in the reference, so for instance if we had a file called 'radios.txt' we could have a reference of the form:- ~tradios~Ptradios.txt~E 2-13 Version 2.5 HyperShell Tutorial Authoring Guide Note that this uses the action code 't', which has the same effect as the reference flag. 2.2.4 Menu systems HyperShell can be used as a versatile menu system, but cannot remain resident with heavyweight software or software requiring lots of data storage. It can still be used with such systems, as it permits 'chaining' and allows an exit code to be given on exit. A simple menu system can be built using a frame for each menu. The higher levels of menu consist of frames containing choices leading to frame references to the lower levels. At the bottom level, selection of a reference will cause the invocation of a program command line. A simple one frame menu can be used to drive a small number of programs. This example shows the actual text in the hyperfile, but can be built using the HyperShell editor, entering an empty HEADER item and the text from the FRAME as below:- .HEADER .FRAME menu1 --- My Menu --- ~A1. Accounts~PDaccounts~K1~E ~A2. Invoices~PDinvoices~K2~E ~A3. Payroll~PDpayroll~K3~E ~A4. Spreadsheet~PE123~K4~E ~A5. Exit~PQ~K5~E . This menu allows the options to be selected as normal, or by use of the numeric keys 1 to 5. Note that the spreadsheet option causes the program to be chained rather than executed as a subprocess, to allow the spreadsheet to have all the memory to itself. 2-14 Version 2.5 HyperShell Tutorial Authoring Guide This little example can be tried out, although of course the programs will not be available. The null header can be used in other hyperfiles, and will suppress the default header display. 2-15 Version 2.5 HyperShell Guidelines Authoring Guide Chapter 3 Guidelines 3.1 Naming The names of frames and other items in the hyperfile are a very important ingredient of the file, and careful naming will contribute both to the setting up and to the use of the hyperfile. The names of items are not limited to single words, and can contain spaces. It is preferable to avoid multiple spaces, and you must ensure that no trailing spaces are added to the name. The name, when used as a key, is not case sensitive, so the most appropriate case mix can be used for the name. Names of items must not exceed 30 characters, but is is hoped that the majority will not exceed half of this. Names should be as simple as possible, whilst retaining sufficient text to be meaningful and distinguishable. 3.1.1 Frame names The choice of suitable frame names is most important, and the names should be chosen as part of the planning activity, rather than as and when you need to supply them. As the names are used in references from other frames, they could be chosen to match the words or phrases used in the text. This is very much a chicken and egg situation, as you may well want to enter the text after setting up the skeleton file. One way of achieving this is to produce a list of temporary names for the frames to act as place holders. Once you have entered the text for all the frames, and before you have added any references, you could study the text to see what form the references would take. You can then make the references consistent, change the frame names to reflect these, and autoreference the frames. This will help you to see if sufficient references have been flagged. 3-16 Version 2.5 HyperShell Guidelines Authoring Guide 3.1.2 Frame Titles The frame title text is almost as important as the name. It appears in the contents list and search list, and is used in the fast search. It is therefore important to choose a title which will give a good indication of what the frame is about. 3.1.3 Other items The note, menu and script names are important only if they are directly referenced from the frame or note text, but it is obviously helpful to keep these names short and meaningful for all cases. The menu name and the note name will be displayed at the top of the respective popup displays, so should be kept to a length commensurate with the options or text lines. 3.2 Style The hyperfile should be clearly laid out to permit ease of maintenance. The HEADER and FOOTER should come at the start of the hyperfile. Global notes, menus and scripts should come next in the file, and should be grouped by type. The INDEX specifier should come next, followed by the frame specifications. Each frame specification contains the FRAME section, followed by any local notes, menus and scripts. The format and content of the information should be consistent. The frames and notes should be written in plain, simple to understand language, and technical terms should be confined to the vocabulary of the intended user. Terms should be consistent in use. Text should be presented in short paragraphs, and should have a consistent left hand margin and a reasonable right hand margin. The justification of text by inserting extra spaces throughout the line to give a uniform right hand margin is not recommended, as it may cause references to become inaccurate, and is now widely recognized as not being of any help when viewed on a screen in this form. The information held within a frame or a note should be complete, and capable of being read on its own. A frame should not present more than half a dozen different concepts, and a 3-17 Version 2.5 HyperShell Guidelines Authoring Guide note should only present one new concept. The information must be as accurate as possible as any inaccuracies will reduce the users confidence. 3.3 Developing a hyperfile Before producing a hyperfile, it is advisable to decide what form it is to take, what fixed information is to appear on the frame display, whether any changes to the control menu are necessary, whether any keys are to be mapped globally or locally, and whether any special highlighting schemes are to be used. These factors can then be taken into account when producing the main text. 3.3.1 Using existing material Existing textual files, provided they are not special format Word Processor files containing control characters etc., can be adapted fairly readily. A text editor or word processor can be used to break the file into sections, inserting a .FRAME section header before each, with a suitable topic name. The HyperShell editor can then be used to alter the layout of the frames, to split the frames into further frames or local notes, to add references using autoreferencing, and to restructure the hyperfile. The hyperfile checker can also be used to add cross references using the autoreference facility, and to check the cross reference integrity of the hyperfile. Small text files can be inserted into frames by use of the insert file facility in the editor. Small text files can be used as popup notes, although it is preferable to integrate these with the main hyperfile, as global notes. 3.4 Types of application For narrative hypertext, the frames should be organised so that a logical thread can be followed. Supporting threads then form offshoots from this main thread. The resultant structure will probably be a network structure, based on a linear or 3-18 Version 2.5 HyperShell Guidelines Authoring Guide hierarchical backbone. Global and local notes can be used in support of the main text. For a help system, each frame can relate to a particular command name, command mode or technical term. Each frame should provide a complete packet of information, and supportive frames need only be produced and referenced as required. The structure for a help system is usually a hierarchy, with occasional cross-references forming network links. Global and local notes can again be used to explain odd terms used in the main text. For context related help, a number of 'entry' frames can be created, each supporting a hierarchy of further information, breaking down the detail of a topic; a top level frame providing a menu of these entry frames is also useful as a general entry point. HyperShell can be used as a context related help facility from your own programs. Your program needs to execute the HyperShell program, specifying the hyperfile name and the 'entry' frame name as parameters. HyperShell can set its exit status to pass numeric information back to your program on exit, if required, by use of a numeric parameter on the Q action. For a menu system, each frame forms a menu node in a hierarchy, although a hierarchy is not strictly necessary. Input fields can be used to supply parameters to programs. Dynamic menus formed from wildcard directories can be used to select a file to be used as a parameter, the resultant value being placed in a variable prior to program invocation. Scripts can be executed to perform sequences of programs, and to do limited validation on input parameters. The HyperShell exit status can be set by use of a numeric parameter to the Q action, and this may be tested in a batch command file to influence the control flow. For an expert system, a hierarchy of frames can be set up to reflect the nodes in a decision tree. Hierarchies of menus can be used as well as, or instead of frames in this decision process. Local notes can be used as 'help' about choices. Scripts can be used to perform limited processing and decision making using control flow and expression evaluation. For computer aided instruction, a sequence of frames can present information about a topic, then offer a multiple choice answer frame. Correct answers move on to next topic frame, incorrect answers move back to original topic frame. Variables can be used to monitor progress and record error levels. For user interface prototyping, a number of different frames can be set up to present alternative layouts for an application input screen. Input fields, menus, notes and scripts can be used to simulate interaction style. Programs can be executed to provide substance to the application. 3-19 Version 2.5 HyperShell Guidelines Authoring Guide For a DOS manager, a basic script running extended directory listings should be set up to allow browsing of directory structures and examination of text files. Actions to take against a particular file can then depend on file type, or could be selected from menus. Use of system variables < and > permit file name and extension to be accessed within the script. For a general text file viewer, with supporting 'topic' hyperfile, a hyperfile should be set up with topic frame names chosen to pick up topics mentioned in the general text files. Autoreferencing should be switched on in the setup script using the action 'O41'. For an adventure system, the network of frames can be made as complex as possible, and menus, notes and scripts can be used to good effect. Variables can be used to hold the state of play. The 'ghost' highlighting scheme is effective in an adventure, as the text highlighted in this manner is not visible until the mouse cursor is moved over it. A new wave of adventures, known as 'hyperware', is due to arrive shortly, and will use hypertext principles, albeit in a graphic context. 3.5 Master hyperfile Where a number of hyperfiles are used together, it is useful to bind them with a master hyperfile which describes each and references the introductory frame in each. More complex structures are, of course, possible, and the structuring then depends on the application. 3.6 Alternative structure An alternative hypertext structure is possible which permits existing text files to be more readily adapted to a hypertext system. With this structure, a small controlling hyperfile may be set up, which may provide a set of supporting frames and switch on autoreferencing. The main hypertext material will be held in a number of simple text files. These files will contain cross references to other such files in the form ~Areference~PTfilename.txt~E. These cross references could occur anywhere in the text of the file, and would be highlighted when the file is browsed. Other forms of highlighting can be chosen 3-20 Version 2.5 HyperShell Guidelines Authoring Guide by using ~F, ~N, ~M etc. as introductory flags. The 'file as note' reference is particularly applicable to this form of hypertext structure, and permits a set of supporting popup notes to be supplied from small text files. These can contain references to further note files, or to further text files to be 'typed'. The control hyperfile could provide an action in its header or footer text, or on its control menu, which will have the action T@D*.TXT (or T@L*.TXT if there are more than 20 text files). This will enable a menu of these files to be presented for initial selection. Of course the files could be grouped by initial letter and a number of actions of the form T@DA*.TXT, T@DB*.TXT etc. could be provided, possibly from a menu. Also the popup notes can be made available from a menu in a similar fashion using the action t@D*.NTE. The MSDOS subdirectory facilities provide a convenient means of structuring sets of text files in a hierarchy. The 'C' action allows selection of a subdirectory, and the same set of dynamic menus can be used at each level. The original directory path is always available via a system variable for when a return to 'base' is required. The intermediate levels of directory pathname can be stored in a list to permit 'backtracking'. Other forms of reference can be used in the text files, and the text file display will be reentered after a Note display, and after DOS command execution. Explicit reentry can be achieved by including ';T' at the end of any action strings in other forms of reference. It is not strictly necessary to have a controlling hyperfile at all. If a simple text file with embedded references etc. is named instead of a hyperfile when HyperShell is invoked, then that file will be treated as a hyperfile with one frame containing the text in the file. The degree of integration of the two approaches is variable, and it is quite possible to have a hybrid approach offering substantial material from both hyperfiles and text files. The alternative approach has the advantage that the text files and notes can be produced 'on the fly' using a text editor possibly driven from the controlling hyperfile. This offers a number of attractions to those gathering information for cross referencing. 3-21 Version 2.5 HyperShell Advanced techniques Authoring Guide Chapter 4 Advanced techniques 4.1 Programming The HyperShell browser can be thought of as an interpreter. It is similar in many ways to a high level language interpreter such as BASIC. Because it was designed for the presentation of information, it does not contain conventional language statements, floating point arithmetic, arrays or control structures. Nevertheless, a lot of conventional programming constructs can be achieved using the SCRIPT facility, and the set of actions. We will approach this topic as we would a programming language, and will demonstrate each construct by giving the equivalent BASIC statements, where possible. 4.1.1 Actions The 'action' is the HyperShell equivalent of a command in a normal programming language. An action is a command string which causes an action to be taken depending on the first letter of the action string. The parameters or operands of an action comprise the remainder of the action string. This part of the string can be supplied literally, or can be supplied as the result of a function, which is called an 'action modifier' in HyperShell. Thus to set a variable to a constant value, the action would be:- Vafred This would give variable 'a' the value 'fred'. To set the variable dynamically to a value chosen from a menu, the action would be:- Va@Mnames 4-22 Version 2.5 HyperShell Advanced techniques Authoring Guide This would popup the menu called 'names' to allow one of a set of names to be selected by the user. The selected name would replace the modifier string in the action before it was executed. Action modifiers can be 'cascaded' to give complex interaction functionality. For example, to type a file selected from a menu formed from a directory listing of files with a wildcard specification input from the user, the action would be:- T@D?Wildcard specification This would prompt the user for a wildcard specification, which would be used to select files from the current directory to form a menu from which the user could select a file to type. If the result of an action modifier is not usable in its provided state, it can be further formatted using a format string:- D@D*.DAT|COPY %s A:%s This would present a menu of all files with the extension .DAT in the current directory, and would then copy the selected file to the A: drive. 4.1.2 Variables Variables do not need to be declared, and come into existance by assignment. Single letter variables are assigned using the 'V' action, and take the value of the remaining text in the action string. e.g. Vafred (BASIC LET a = "fred") assigns the value 'fred' to the variable 'a'. The variable can have another value subsequently assigned to it, or it can be cleared by use of a null string (a string of zero length). Named variables are assigned using the 'l' action, and can only be assigned values from single letter variables. e.g. laname (BASIC LET name = a) Note that the name in this case can be provided from an action modifier, or from a variable token expansion. e.g. la$b This loads the contents of 'a' into the variable whose name is the contents of variable 'b'. There is no equivalent of this in BASIC, or any of the other common interpretive languages for 4-23 Version 2.5 HyperShell Advanced techniques Authoring Guide that matter. The variable may be used in a number of ways. The most common is as an expansion token in the frame or note text, or in an action string. The above example does not reflect the full power of this as the variable can in fact be expanded anywhere in an action string after the first letter. So for instance, to load the variable whose name is a concatenation of the contents of the variables 'c' and 'd' from the single letter variable whose name is contained in variable 'x', we would write:- l$x$c$d The named variable expansion token takes the form:- $(name) Where 'name' is the name of the named variable. This itself can be supplied by a single letter variable. e.g. $($b) Thus to do the opposite of 'la$b' we would write:- Va$($b) Variable token substitution is done in frame and note text before displaying the text (so variables can contain reference flags). Variable token substitution is done in action strings AFTER any action modifiers have been actioned and before the action is executed. Thus an action string of the form:- Vb?value of b could have a value of '$c' typed in by the user, which would be expanded to the contents of variable 'c' before the assignment was made. A variable token expansion can be 'deferred' one step by putting two $ signs. This will be converted to one $ on the first expansion and will be expanded on the second. Thus a variable token in an action string in a reference on a frame display should have two $ signs, as the expansion on display would otherwise preempt the intended expansion when the reference was actioned. Single letter variables can be used directly in an integer expression action modifier. Thus an action of the form:- 4-24 Version 2.5 HyperShell Advanced techniques Authoring Guide Va=b+c (BASIC LET a = b + c) will do as expected. Variables can also be used in this manner in tests, thus we can have:- va=b+c+d;je10 (BASIC IF a = b + c + d GOTO 10) When a variable comparison is performed, a number of condition codes are set, and can be tested. If the variable and test string are numeric, the comparison is a numeric comparison, otherwise it is a string comparison and works as an ASCII collating sequence string compare. This compares variable 'a' against 23 and jumps to LESS if it is less than 23. va23;jlLESS This compares variable 'n' against 'fred' and jumps to FRED if it is equal. vnfred;jeFRED Also, a substring and superstring compare is done, so that you can test whether the variable is contained within the string, or contains the string. This sees if variable 'e' is one of 'one','two','three' and jumps to Lone, Ltwo or Lthree if so:- veone two three;jw$e It is sometimes useful to test whether the variable is defined at all. This sees if variable 'j' is defined and jumps to DEFINED if so:- vj;jdDEFINED A number of system variables are available, mapped to the numeric and other characters. Most of these cannot have values explicitly assigned to them, but can be expanded in exactly the same way as single letter variables. See the reference guide for details of these. It is often necessary to break a string into, for instance, a number of fields. The fields can be specified as those strings separated by a specified character. Thus a string could have the form "aaaa:bbbbbb:ccc:dd". This can be split into a number of variables with an action of the form es:abcd 4-25 Version 2.5 HyperShell Advanced techniques Authoring Guide Where 's' is the variable containing the string, and a,b,c and d are the variables to receive the fields. In the example above, variable 'a' would receive 'aaaa', variable 'b' would receive 'bbbbbb' etc. Whilst arrays are not supported as such, constant arrays can be implemented using a menu, and using the form:- Vn@Mnames($v) This uses the value of variable 'v' as an index into the set of strings specified in the menu called 'names', returning the indexed entry and assigning it to variable 'n'. Associative arrays i.e. arrays subscripted by character strings, can be set up using menus with entries containing the key string and the associated string, and indexed using the form:- Vs@Msurnames[$n] This takes the contents of variable 'n' as a key to look up an entry in the menu 'surnames', returning the action string from the located entry and assigning it to the string 's'. The menu 'surnames' would have the following form:- fred|jones jim|smith joe|davies harry|hodgson nick|taylor 4.1.3 Scripts The script facilities in HyperShell permit a form of programming to be achieved. A simple sequence of actions may be performed in a script, and control flow actions are provided to allow loops, conditional branching and computed branching to occur. A trace facility is provided to assist with the debugging of scripts. HyperShell does not yet have any specific loop control instructions, but loops are easy to program using the Jump action. Thus, a BASIC loop of the form:- FOR A = 1 TO 20 ... NEXT A is handled as follows:- 4-26 Version 2.5 HyperShell Advanced techniques Authoring Guide VA1 Lloop ... VA=A+1;va21;jlloop As the expression evaluation modifier sets the condition code, a decreasing loop is easier to use when the variable is not used in the loop body. VA20 Lloop ... VA=A-1;jnloop Beware an unexpected side effect of HyperShell compound statements. If further actions follow a Jump instruction in a compound statement, the further actions are executed regardless of whether the jump is actioned. Computed GOTO statements in BASIC of the form:- ON a GOTO 110,120,130,140 can be coded in HyperShell with a simple Jump specifying the value of a variable. J$a The variable, 'a' in this case, need not contain a numeric value, as a label can be any alphabetic string. E.g. to branch depending on the value returned from a confirmation prompt:- J$c ... LYes ... actions if Yes ... Jend LNo ... actions if No ... Lend Of course, the Jump action can have its parameter supplied from one of a number of action modifiers, so a number of potential labels could be presented as a menu:- 4-27 Version 2.5 HyperShell Advanced techniques Authoring Guide J@Mchoices It is not possible to supply the name of a label in an 'L' action in this fashion. 4.1.4 Simple interaction The BASIC interaction commands are very useful for communicating with the user. HyperShell has some equivalents to the simple interaction commands as follows:- Vn?Enter your name (BASIC INPUT "Enter your name";n$) PHello (BASIC PRINT "Hello") PYour name is $n (BASIC PRINT "Your name is ";n$) Do not confuse the use of the dollars in the last example. HyperShell uses dollar signs for an altogether different purpose. HyperShell provides powerful extensions to this interaction, however. If one of a number of fixed strings is to be entered, the set of strings can be presented as a menu. If a more elaborate prompting method is required, a note can be popped up as a dialogue box. The menu or note are then used to supply the value to the variable:- Vt@MCar type Vc@NConfirm Where a single character input is required, the Key function can be used. This is coded as e.g. Vx&KPress a key And is the equivalent of the BASIC:- 30 PRINT "Press a key" 40 X$ = "" 50 X$ = INKEY$(): IF X$ = "" GOTO 50 4-28 Version 2.5 HyperShell Advanced techniques Authoring Guide 4.1.5 Functions A number of string functions are available as 'action modifiers'. Strictly, all action modifiers are functions of a sort, but the string functions are classified as 'functions' to separate them from the dynamic menus and other string providers. The string functions provide a set of facilities analogous to the BASIC functions, although even those returning a numeric result are classified as string functions in this case, both because they operate on strings, and because they return the result as an ASCII string regardless. The functions take the form:- &FParg Where 'F' is the function code, 'P' is an optional parameter and 'arg' is the argument string to apply the function against. The function codes are as follows:- L - Length of argument (BASIC LEN) A - ASCII value of first char of argument (BASIC ASC) C - character with ASCII value argument (BASIC CHR$) Nn - nth character in argument Sn - substring starting at nth character of argument (BASIC MID$) T - Title of frame with name argument Uc - substring of argument up to, but not including character 'c' Fc - substring of argument from character 'c' inclusive Ic - index of character 'c' in argument, or 0 if not found (BASIC INSTR) K - character typed in response to argument as popup message (Basic INKEY$) 4.1.6 File input/output Most languages provide some form of file I/O. HyperShell provides a fairly straightforward means of reading or writing to 4-29 Version 2.5 HyperShell Advanced techniques Authoring Guide a file. It is not intended as a fully fledged language, so only permits one input and one output file at a time. It is possible to have one file open for input and to keep this open whilst another file is opened, read and closed, however. To open a file for reading or writing, the action:- rfilename / wfilename is issued (r for read, w for write). To read a record, two mechanisms are provided. The formatted read allows a set of variables to be loaded from 'fields' in a text record. The 'R' action is used for this:- R:abcdef Reads the next input record and splits it into variables a,b,c,d,e and f on a separator ':'. The other means of reading an input record is provided via the action modifier '!'. This can be used in a number of ways. The simplest form is '!' by itself, which returns the next input record. The form:- !Fkey reads the next record starting with the string 'key'. If it is necessary to read the frist record in the file starting with the 'key', the format:- !Lkey is used instead. Thus this method can be used to provide a lookup facility. This lookup is performed sequentially, however, so cannot be practically used if the file concerned is huge. File output is done using the 'W' action. This simply takes its argument as the record to be written. The record can be formed from any of the standard action modifiers, or from variable tokens:- W$a:$b:$c:$d:$e:$f which would write a record made up of the variables a to f separated by ':' characters. 4-30 Version 2.5 HyperShell Advanced techniques Authoring Guide 4.2 Form Fill HyperShell frames can also be used as data entry forms or database browsing forms. This is brought about by one powerful type of reference - the input field. An input field is like any other reference, until you select it. It then becomes an input area into which you can type a string. It is generally the case that the input string is used to set a variable, and that the variable is displayed in the field until it is selected. The width of the field is generally specified in the field specification, as it is this which determines the maximum size of the field. A typical input field would look like:- ~I$v~W10~PVv%s~E This specifies an input field of length 10, in which the variable 'v' is displayed. After entering a string, it is assigned to the variable. Where a number of fields are supplied in a frame to form a formfill screen, they can be 'chained' to the next input by use of the 'I' action. This causes the next input field to be selected. e.g. ~I$v~W10~PVv%s;I~E does the same as the above field, and then selects the next input field. The user sees this as a typical formfill interaction, and can press ESCAPE to cancel the sequence of inputs. So, what do we do with the data we have entered. One thing we could do would be to write it to a file. An action reference in the frame text could be used for opening the file for starters:- ~AOpen file for writing~Pwdata.txt~E The last input field could then write the data out after input:- ~I$f~W10~PVf%s;W$$a:$$b:$$c:$$d:$$e:$$f~E This would write out a line containing variables 'a' to 'f' separated by ':' characters. As an alternative, a separate action reference can be used for writing a record, so that changes can be made to the fields before writing:- 4-31 Version 2.5 HyperShell Advanced techniques Authoring Guide ~AWrite record~PW$$a:$$b:$$c:$$d:$$e:$$f~E Note that the double dollars are needed to stop the variable expansion taking place when the frame is displayed. To close the file, another action reference of the form:- ~AClose file~Pw~E can be supplied. How about using the form to browse through a database. To open a file for reading, we have an action:- ~AOpen for reading~Prdata.txt~E If the database consists of text records with fields separated by a special character (like ':' above), we can read a record into a number of variables with one action string:- ~ARead file~PR:abcdef;y~E This reads the next record and refreshes the screen, allowing any variable expansion tokens for the variables input to be expanded. These could be in input field specifications, or elsewhere in the frame text. If we want to perform a lookup in a text file, the 'R' action cannot be used. In this case we could use an input field to input the first variable as a key, and lookup the record. ~I$a~W20~PVr!L%s;er:abcdef;y~E This rather complex action uses the input string as a key to look up a record starting with the key field, reading the record into variable 'r'. It then expands 'r' into a,b,c,d,e and f before refreshing the screen to display the values. Note that a slightly more complicated action is required in practise, as it has to handle the case where the record is not found - the above example would set all variables to a null string (which may be acceptable in some cases). The 'immediate reference' flag can be used with form frames to select the first input field, or to execute a script to open files etc. prior to any processing. 4-32 Version 2.5 HyperShell Glossary Authoring Guide Appendix A Glossary Action An action is a command string executed by HyperShell. This command may be mapped to a key, executed when a reference is selected, selected from a menu or performed as a step in a script. Cursor A single character line or block used for indicating a 'current position' upon the computer screen. HyperShell has its own 'mouse cursor', which is a block, and the normal text cursor, which is usually a blinking underscore character. The text cursor is only used when inputting text. The mouse cursor is used for selecting references and menu options. Frame The unit of display of HyperShell. A Frame is the information displayed to describe a topic, and is usually presented in a full screen display. Global/local A HyperShell item, such as a Note, Menu or Script is either global or local. If it is Global, it is available from all frames and other items. If it is Local, it is only available when the frame to which it is local is currently displayed. Hyperfile A hyperfile is the text file used to drive HyperShell. It contains the text for frames and other items, specifications of menus, scripts etc. and embedded reference flags to indicate cross reference links. Item An item is one of the HyperShell control structures, such as frames, notes, menus, scripts, headers, footers etc. Menu A menu is a popup display offering a choice from a number of selections. 4-33 Version 2.5 HyperShell Glossary Authoring Guide Mouse A mouse is a device used for controlling the location of a cursor on the screen. A mouse usually has one or more buttons, which act like keys on the keyboard. In HyperShell, a cursor is provided to imitate the action of a mouse cursor, even if a mouse is not available. A direct mouse driver is also supplied for those who have a mouse. Note A note is a small popup display of textual information. This display can occupy a section of screen nearly as big as a full screen display. Option An option is a control setting for HyperShell, used to control the way in which HyperShell runs and the colour schemes used to display the items. Popup A type of display where a small area of screen is overwritten temporarily by a highlighted block of text used as a menu or some form of display. When the display is finished with, the area of screen is rewritten with its original contents. Reference A highlighted word or sequence of words in a frame or note display, which can be selected to perform some kind of action, such as moving to another frame display. Select You 'select' a reference by moving the mouse cursor to it and either pressing the RETURN (or ENTER, or that big key on the right of the alphabetic group you use for finishing lines), or the left hand mouse button. Script A script is a sequence of actions grouped together. It is similar to a small program, and can contain programming contructs. Variable A variable is a named storage area used to hold strings of characters and numbers. - END OF DOCUMENT - 4-34 Version 2.5 HyperShell Glossary Authoring Guide Table of Contents Chapter 1 Introduction 2 1.1 Introduction 2 1.2 Authoring 2 Chapter 2 Tutorial 4 2.1 File contents 4 2.2 Tutorial 4 2.2.1 Simple hypertext 4 2.2.2 Adding features 7 2.2.3 Adding further features 10 2.2.3.1 Help 10 2.2.3.2 Narrative flow 12 2.2.3.3 Supporting files 13 2.2.4 Menu systems 14 Chapter 3 Guidelines 16 3.1 Naming 16 3.1.1 Frame names 16 3.1.2 Frame Titles 17 3.1.3 Other items 17 3.2 Style 17 3.3 Developing a hyperfile 18 3.3.1 Using existing material 18 3.4 Types of application 18 3.5 Master hyperfile 20 3.6 Alternative structure 20 Chapter 4 Advanced techniques 22 4.1 Programming 22 4.1.1 Actions 22 4.1.2 Variables 23 4-35 Version 2.5 HyperShell Glossary Authoring Guide 4.1.3 Scripts 26 4.1.4 Simple interaction 28 4.1.5 Functions 29 4.1.6 File input/output 29 4.2 Form Fill 31 Appendix A Glossary 33 4-36 Version 2.5