****************************************************
Running HeliOS command lines from DOS/AREXX commands
****************************************************

This is one of the most powerful features of HeliOS, and it is well worth
becoming familiar with the methods of attaching the execution of HeliOS
programs to command macro keys.

The HeliOS system provides various methods of executing DOS or AREXX
command lines, and this DOS/AREXX external command support can be simply
adapted to execute HeliOS programs also.

There are several provisions within HeliOS for executing DOS or AREXX
commands:

1. From the user interface menus

2. From the user interface macro key command allocation system

3. From your software, using the DOSCMD function

The first two of these methods also allow the command line to be executed
as HeliOS code, by using a special introductory command.

The second method, using macro keys, is the most useful, because it opens
up the possibility of executing any HeliOS program at the touch of a key.

One example of the use of this might be to preload the HeliOS dictionary
with special sets of words for particular tasks: several different commands
to load different word sets could be attached to function keys.

Another example might be to attach the "FORGET **CORE**" command to one of
the function keys, to enable easy clearing of the dictionary.

In summary:

The following functions allow a DOS/AREXX command to be interpreted as a
HeliOS command line by using a special introductory command:

1. The DOS/AREXX command menu option in the editor or interpreter.

2. The DOS/AREXX macros using command keys in the editor or interpreter.

Note that the DOSCMD program statement does not support the interpretation
of the command line as HeliOS code: this would be somewhat pointless!


*********************
Command string length
*********************

As with standard DOS/AREXX command strings, the HeliOS command lines may
be up to 100 characters in length.

This is not at all a restriction, because this command line can be used to
RUN any HeliOS program, which in turn can RUN other programs, so the command
line actually gives you unlimited scope for execution of HeliOS code.


******************************
Creating HeliOS command macros
******************************

The special HeliOS command DOS/AREXX macros can only be created and attached
to command keys in the editor environment using the normal "Set DOS/AREXX
macro" menu option.

HeliOS command macros can be saved as usual along with all other macros.


*****************************
Running HeliOS command macros
*****************************

Although HeliOS command macros may only be created in an editor, they can be
executed either from within an editor or from the interpreter environment.


***************************************************************
Setting up "HeliOS command line" versions of DOS/AREXX commands
***************************************************************

When you execute a DOS/AREXX command from a macro or the menu option the
command line may be set up by a special code word to run as a HeliOS code
line instead of a DOS or AREXX command line.

There are actually two special command words which perform this function
in slightly different ways: these are "H>" and "E>".

The special code must consist of either "H>" or "E>", and must be placed at
the very start of the command line.

In normal circumstances, unless the special command word is included at the
start of the command line, the operation defaults to the DOS/AREXX command.

By including one of the special commands at the start of the line all the
rest of the line will be interpreted and executed as HeliOS code.


*************************
The execution environment
*************************

If you are in an editor when the DOS command is evoked, and if you specify
that this is a HeliOS command line, you will be ALWAYS be taken out of the
editor into the interpreter before your command line is executed.

If you are already in the interpreter the command line will simply be run
within the interpreter environment.


*************************************
The differences between "H>" and "E>"
*************************************

There are two different codes because the execution of the HeliOS command
line can be carried out in two ways, as follows:

Using the   H>  command ->  The interpreter goes through a full "session"
                            procedure exactly as if you had typed the line
                            of commands at the interpreter command line.

Using the   E>  command ->  The interpreter runs the code line without any
                            of the auxiliary actions associated with normal
                            interpreter sessions.

The E> command is useful if you want to run a command without explicitly
performing an interpret cycle, such as when you evoke the command from an
editor and your command line is to load a file into another editor.

For example, suppose you executed these command lines from an editor macro:

H> 3 EDIT S:Startup-sequence

or

E> 3 EDIT S:Startup-sequence

Both these would end up placing you in Editor3 with the startup-sequence
file loaded ready to edit.

Using the H> version you would leave the editor you were in and go out into
the interpreter, then you would see the interpreter go through its full
session cycle, then you would then return to the editor environment with
your new file in Editor3.

Using the E> version you would move directly to the new editor without
going through the interpreter session: although the E> procedure does go
via the interpreter, no explicit interpreter session cycle is carried out.

The latter action is preferable because it is quicker and less visually
distracting.


**************
General useage
**************

With this general mechanism using H> and E> it is easy to set up hot-keys
to carry out commonly required HeliOS functions.

For example, if you wanted to set up a special command key to perform the
"FORGET **CORE**" function, so you could simply create a DOS macro with the
following command line:

E> FORGET **CORE**


**************
Important note
**************

Remember that you can only create a DOS macro within an editor, but you can
USE the macro either in the editor or interpreter.


********************************************
Special useage within the HeliOS HELP system
********************************************

The HeliOS interactive environment has built in support for a powerful
and comprehensive user-configurable interactive help system.

The central feature of this help system is the ability to call up help
texts, or to run example programs, simply by placing the cursor over a
word and pressing a command key.

This interactive help system is controlled via the use of HeliOS macros
running HeliOS command lines, and provides a fully user configurable
interface to a fully user re-definable help system.

This is the most powerful and flexible help system ever seen in an Amiga
programming language, and it is very important to learn how it works in
order to make maximum use of its power.

The following part of this document explains the special commands which
are available within HeliOS command lines macros to allow control of the
help system.


*******************************
A note on Vocabulary Help files
*******************************

All of the many features of the HeliOS help system are controlled using
special files called Vocabulary Help files.

Only one Vocabulary Help file can be active at any time, but there are
provisions for swapping or modifying this file as required.

HeliOS can be set up to automatically load any file as a Vocabulary Help
file at system startup time.

Alternatively, there are menu options for loading different Vocabulary
Help files, and there is a HeliOS command word, called "VHELP", which
allows direct access to, and manipulation of, Vocabulary Help files.

Vocabulary Help files are ordinary ASCII files and can be edited in any
text editor (such as the HeliOS editors).

A Vocabulary Help file can contain the following elements:

1. Plain ASCII text which can act as a commentary on, or description of,
   the contents of the Vocabulary Help file.

2. Help texts (one or two pages) which can be associated with any word.

3. Three sets of specially encoded information which can be associated
   with any word.  This information can specify such things as paths
   and filenames to example programs or extended help files.

4. A command file name which allows dynamic pre-processing of the help
   information by running a user defined HeliOS program whenever the
   Vocabulary Help file is loaded.


******************************************************
What you can do with the HeliOS Vocabulary Help system
******************************************************

The basic idea of the HeliOS help system is that the cursor can be placed
over any word within the text in one of the HeliOS editors, or the HeliOS
interpreter command line, and then help can be called up for that word.

The interesting thing is that the help which is called up can have a wide
variety of forms, and is fully user definable.

You can do things like this:

* Present one or two pages of help text in a pop-up requester.

* Display a help file in an external text reader.

* Display and edit on-line a help file in an external text editor.

* Display and edit on-line a help file in one of the HeliOS editors.

* Load into a HeliOS editor a special comprehensive HeliOS help file
  and jump to all references to the specified word.

* Load into a HeliOS editor, for viewing or editing, an example HeliOS
  program file.

* Run an example HeliOS program using the stand-alone HeliOS compiler.

* Load and run an example HeliOS program using the internal interpreter.

* Load and edit a Vocabulary Help file.

* Change or modify the existing on-line Vocabulary Help buffer.

...and much more.

In fact the whole system is so configurable that you can virtually define
your own actions.


********************************************************
Using HeliOS macros to access the Vocabulary Help system
********************************************************

The key (excuse the pun) to getting the most from the HeliOS Vocabulary
Help system is to define your own macro keys to specify whatever form
of help you require.

This is achieved by using certain special words within the macro command
line which extract information from any installed Vocabulary help file.

The most important of these words are "substitution" words.

These words basically function by searching the Vocabulary Help file
and substituting themselves with new text strings derived from this file.

Here, as an example of how the special substitution words work, we will
discuss just one of these words, "EXM$":

****
EXM$
****

This word:

1. Reads the word under the cursor in the current HeliOS environment.

   Let us say, for the sake of example, that this word is "MyHelpWord".

2. Combines this word with a preceding "X}" string, forming a new full
   string as "X}MyHelpWord".

3. Searches the currently installed Vocabulary Help file buffer for any
   occurrence of the string "X}MyHelpWord".

4. If it finds a match, it extracts from the Vocabulary Help a following
   string delimited by "{}" brackets, like this:

  X}MyHelpWord{HeliOS:HelpDocs/MyHelpWord}
               ^^^^^^^^^^^^^^^^^^^^^^^^^^
                This string is extracted

5. The extracted string is substituted for the string "EXM$" within the
   macro command line.

Thus, in our example, if we had a macro command line like this:

  H> RUN EXM$

the actual command performed would be:

  RUN HeliOS:HelpDocs/MyHelpWord

This would RUN a HeliOS program file called "HeliOS:HelpDocs/MyHelpWord".


There are three other substitution words besides EXM$, and these are:

****
CUR$
****

This is a very simple substitution word which simply substitutes for itself
the word currently under the cursor in the HeliOS environment.


****
HLP$
****

This is identical in general operation to "EXM$" except that it searches
for a string prefixed by "H}" instead of "X}".

An example of its use might be as follows.

Let us assume that the word under the cursor is again "MyHelpWord".

Let us assume that the matching string in the Vocabulary Help file is:

  H}MyHelpWord{HeliOS:HelpDocs/MyHelpWord}

Let us assume that the command macro is:

  E> 3 EDIT HLP$

so the actual command performed would be:

  3 EDIT HeliOS:HelpDocs/MyHelpWord

This would load the file called "HeliOS:HelpDocs/MyHelpWord" into the
HeliOS Editor3 and present it for viewing and/or editing.


****
FIL$
****

This is identical in general operation to "EXM$" except that it searches
for a string prefixed by "F}" instead of "X}".

Let us consider a more complex example this time.

Let us assume that the word under the cursor is again "MyHelpWord".

Let us assume that the matching string in the Vocabulary Help file is:

  F}MyHelpWord{HeliOS:HelpDocs/MyFullHelpFile}

Let us assume that the command macro is:

  E> 3 $FINDEDIT CUR$ FIL$

where the actual command performed would be:

  3 $FINDEDIT MyHelpWord HeliOS:HelpDocs/MyFullHelpFile

This would load the file called "HeliOS:HelpDocs/MyFullHelpFile" into the
HeliOS Editor3 and search for the first occurrence of "MyHelpWord".

This command would also set up the editor search system ready for finding
any further occurrences of the target word.

There are further refinements which allow you to search for a particular
occurrence of the search string, thus affording a very powerful help search
and browse functionality.


***********************************
Setting up the Vocabulary Help file
***********************************

The Vocabulary Help file can be set up with various sets of entries which
define paths to your help files, as in the examples above.

For example:

H}MyHelpWord1{HeliOS:HelpDocs/MyHelpWord1}
H}MyHelpWord2{HeliOS:HelpDocs/MyHelpWord2}
H}MyHelpWord3{HeliOS:HelpDocs/MyHelpWord3}
H}MyHelpWord4{HeliOS:HelpDocs/MyHelpWord4}
H}MyHelpWord5{HeliOS:HelpDocs/MyHelpWord5}
etc.

X}MyHelpWord1{HeliOS:HelpDocs/MyHelpWord1}
X}MyHelpWord2{HeliOS:HelpDocs/MyHelpWord2}
X}MyHelpWord3{HeliOS:HelpDocs/MyHelpWord3}
X}MyHelpWord4{HeliOS:HelpDocs/MyHelpWord4}
X}MyHelpWord5{HeliOS:HelpDocs/MyHelpWord5}
etc.

F}MyHelpWord1{HeliOS:HelpDocs/MyFullHelpFile}
F}MyHelpWord2{HeliOS:HelpDocs/MyFullHelpFile}
F}MyHelpWord3{HeliOS:HelpDocs/MyFullHelpFile}
F}MyHelpWord4{HeliOS:HelpDocs/MyFullHelpFile}
F}MyHelpWord5{HeliOS:HelpDocs/MyFullHelpFile}
etc.

Note that using by the "F}" entries you can direct help for several words
to one large Help file which can be used for browsing and cross-reference
between functions.

By the way, although the convention is to use the words in the above way,
you can in fact make up your own methods: in effect all the 3 substitution
functions work in an identical way, and it is up to you how you use them.


*****************************
The HeliOS VHELP command word
*****************************

There is a useful HeliOS word, VHELP, which can be used in programs run
from a macro key, or from the command line, or indeed within any HeliOS
program at all, and which allows virtually unlimited programmable access
to the Vocabulary Help system.

Here is the dictionary definition of VHELP:

VHELP         ( various _ _ _ various )

              This is a flexible function for manipulating the HeliOS
              VHelp system, and can have several stack effects.

              VHELP has three separate functions:

              1. Removing the current active HeliOS VHelp file and
                 deallocating all associated resources.

                 In this case you should call VHELP with a 32-bit
                 "0." value on the stack:

                 0. VHELP

                 This use of VHELP returns no stack parameters.

              2. Getting the current active HeliOS VHelp file buffer
                 and its size.

                 In this case you should call VHELP with a 32-bit
                 "-1." value on the stack:

                 -1. VHELP

                 This use of VHELP returns two stack parameters,
                 as follows:

                 - - - VHelpBuffer(l), VHelpBufferSize(l)

              3. Setting a new current active HeliOS VHelp file buffer.

                 In this case you should call VHELP with two 32-bit
                 values on the stack, these being your new VHelp buffer
                 and its size:

                 MyVHelpBuffer(l), MyVHelpBufferSize(l) - - -

                 This use of VHELP returns no stack parameters.

                 This operation will set up the HeliOS VHelp system
                 with your new VHelp buffer, and will automatically
                 de-allocate the old buffer.

                 If you wish to do so, you can, of course, deallocate
                 the old VHelp buffer before allocating your new one.


***********************************
The Vocabulary Help startup command
***********************************

A special command line within any Vocabulary Help file may be used to
run a HeliOS program as soon as the help file has been loaded.

Details of this, as well as more information on the help system in
general, can be found in the documentation file "HelpSystems.Doc".


*************************************************************************
End
*************************************************************************