Simtel MSDOS 1992 June/SIMTEL_0692.cdr/msdos/hypertxt/hs25.arc/HSDEV.LZH/HSREF.DOC

Text File | 1989-05-13 | 143KB | 5,414 lines

               HyperShell Hypertext control system
                   Version 2.5

                 Reference Guide

             Copyright (c) 1988,1989 Text Technology


















    Text Technology
    66 Kennedy Avenue
    Macclesfield
    Cheshire
    England
    SK10 3DE





















                      - 1 -
















                    Chapter 1

                  Introduction




    1.1 Introduction


    This manual is a reference guide for use by HyperShell authors.
    It  describes the format of  the  HyperShell  control  file  and
    describes  the    HyperShell  authoring  tools  -  the  Hypershell
    Editor,  the HyperShell Checker, and  the  HyperShell  formatted
    print program.

    The manner of using HyperShell to browse hyperfiles is described
    in the    Users  Guide, and the fundamentals of writing hyperfiles
    is  presented  in  the    Authoring  Guide, knowledge of which  is
    considered a prerequisite for readers of this document.

    The creation of  the  hyperfile  can be done using a simple text
    editor    or  word processor, or can be done using the  HyperShell
    dedicated editor.  The relevant  chapters  should be referred to
    for details of the  interactive  hyperfile editor, the hyperfile
    checker and the formatted hyperfile print utility.























                      - 2 -








    HyperShell          The Hyperfile      Reference Guide









                    Chapter 2

                  The Hyperfile




    2.1 File contents


    A hyperfile is a simple text file, containing identification and
    formatting details  of    the frames in the hyperfile.  It is made
    up of items general to the hyperfile, and items relating to each
    frame in the hyperfile.  The order of certain items is critical,
    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  Authoring  system  provides  a
    consistency checker which will go some way  towards checking out
    the format of the file for you, but it pays to be careful in the
    first place.


    2.1.1 Remarks

    A  remark section can appear anywhere in the hyperfile,  between
    other  sections.   It  is followed by lines of    text  containing
    information for the  hyperfile    author    only,  and  will  not be
    displayed during a HyperShell session.    The remark section takes
    the following form.


    .REMARK
    text lines

    The  section,  like  all  sections,  is  terminated  by the next
    section identifier (any line starting with '.').


    2.1.2 Check






                       2-3             Version 2.5








    HyperShell          The Hyperfile      Reference Guide




    .CHECK {-options}{+options}

    The  Check  specification is a single line 'section'  signalling
    the settings of flags for use by the  HyperShell Checker utility
    (HC). For details of  the  parameters,    see  the  chapter on the
    HyperShell  Checker.  This section  is    ignored  by  HyperShell,
    although it does signify a new section, and therefore terminates
    a previous section.


    2.1.3 Header


    .HEADER
    (text with references and formatting)

    The header section provides the text that will appear at the top
    of the    frame  display.   By convention it contains the name and
    title  of the frame being displayed, and may also contain  date,
    time, hyperfile name etc.

    Graphic  characters or others from the 256 character set may  be
    used to draw boxes etc.

    The header section is optional.  If omitted, a    default title is
    displayed showing the frame name and title.

    A 'null' header consisting of a .HEADER line followed by another
    '.' line  may be used if each frame is to have a different form,
    and does not need the default title.


    2.1.4 Footer


    .FOOTER
    (text with references and formatting)

    The  footer provides the text that will appear at the bottom  of
    the frame display.  It is usual to position  it  at a fixed line
    location  (Using ~Lnn) so that it appears in the same place  for
    each frame.  The footer  usually  contains  references    that are
    present for all frames in the file, such as a help note display,
    a function key map, a backtrack count display etc.

    Graphic characters or others from the 256 character  set  may be
    used to draw boxes etc.





                       2-4             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    The footer section is optional.


    2.1.5 Global Notes


    .NOTE name
    (text with references and formatting)

    Global notes are notes that are accessible from any frame in the
    hyperfile.  They are usually  for  providing  help  information,
    function  key  displays  and  supportive material for the  frame
    texts.    As notes may contain references, these references may be
    used to provide further information in the form  of other notes,
    or even frames.

    The global note section is optional, and there may  be more than
    one present.  Global notes should be kept together  if there are
    a lot of global items.


    2.1.6 Global Menus


    .MENU name
    (options)

    Global    menus  are  menus  available  from  any   frame  in  the
    hyperfile.

    The global menu section is optional, and there    may be more than
    one present.  Global menus should be kept together if there  are
    a lot of global items.


    2.1.7 Global Scripts


    .SCRIPT name
    (actions)

    Global scripts are  scripts  available    from  any  frame  in the
    current  hyperfile.   Scripts are sequences  of  actions.   Such
    sequences  may    contain  control  flow    actions  for  performing
    conditional branches and repeated  sequences  of  actions.  Each
    line of the script  may  contain  a  number  of actions, up to a
    maximum  length  of  128  characters.  A conditional action in a
    line  affects  remaining  actions  on that line.  The J/j and  L
    actions may  be  used  to  perform  control  flow.   A script is
    terminated when a new frame is referenced.



                       2-5             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    The global script section is optional,    and  there  may  be more
    than  one  present.   Global scripts should be kept together  if
    there are a lot of global items.


    2.1.8 Setup Script


    .SCRIPT SETUP
    (limited actions)

    The  setup  global script is acted upon when  the  hyperfile  is
    loaded, and when the  hyperfile  is  reentered    after displaying
    frames    from  another  hyperfile.  It is  used    to  set  up  key
    mappings and to set control options.  An initial note display or
    certain other  actions    may also be performed at this stage, but
    remember that the script is used on reentry  as  well as at load
    time, so may well be executed many  times when the user switches
    between hyperfiles.  It is imperative not to do a frame display,
    or any action which would ultimately cause a frame display.

    The setup script is optional.


    2.1.9 Index

    The .INDEX line may  be  present anywhere before the first frame
    specification.    It signals that an index file is usually present
    for the  frame.   An  index file is useful when the hyperfile is
    above a certain size, as it saves HyperShell from having to read
    all the way through the hyperfile  to build its internal index.
    Opening and reading the index file has its  overheads,    however,
    so its not always  helpful  to    have  the index file in use.  An
    index is generally of use when a hyperfile has above  30  frames
    of reasonable size.

    The index file is  maintained  automatically, and is kept in the
    same directory as the hyperfile.  It has the same  name  as  the
    hyperfile,  but  with  an  extension of .HIX. If you modify  the
    hyperfile, HyperShell will detect this and rebuild the index for
    you.  If you delete the index, a new one will also be built.  If
    the .INDEX line is not present, HyperShell  does  not try to use
    index files.


    2.1.10 Frames

    Frame  specifications  are  bracketed  by  the    .FRAME and  .END
    keywords.  The    .END keyword can be ommitted, as the next .FRAME
    will  terminate  the current one.  However the .END  keyword  is



                       2-6             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    used by the hyperfile editor to determine the scope of the items
    following a frame reference,  so  should  occur  after all local
    items  and before any .REMARK or .CHECK which refers to the next
    frame.    There  must  be  at  least  one frame specification in a
    hyperfile, and there may be as many as three or four hundred.


    .FRAME name
    .TITLE title text
    (frame text with references and formatting)
    .MENU name
    (options)
    .NOTE name
    (text with references and formatting)
    .SCRIPT name
    (actions)
    .END


    2.1.10.1 Name

    The frame name provides  the  key  to  the  frame  and    is  very
    important because of this.  When frame references exist in text,
    it  is    useful to use the word (or set of words) in the text  as
    the  key  to  the  frame  reference.   A name should be  chosen,
    therefore, that will be the form  used    when  referring  to  the
    topic of the frame.  Thus 'deleting' is a bad choice for a frame
    about deleting, as it would more  likely  be  the  word 'delete'
    when used in the context within a frame  text.     Fortunately the
    rule is not rigid,  as    frame references can contain parameters,
    hidden from display, that refer to the real frame name.


    2.1.10.2 Title

    This line is optional.    However, note the following:-

    The frame title is  normally  displayed  in  the  frame  display
    header.   It  is  also displayed in any paged  menus  containing
    frame lists,  and  is  used  by  the  'search' command to locate
    frames about particular topics.

    It is therefore reasonably important, and well worth providing.


    2.1.10.3 Text

    The frame text comes after the frame name (and title) lines.  It
    contains the text specific to the frame.  This will be displayed
    between the header and footer.



                       2-7             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    Graphic and other characters from the  256  character set may be
    used to draw boxes etc.

    The text may contain embedded references to other frames, notes,
    menus  and  other  actions.   Frame  references  can  either  be
    explicitly marked or may  be automatically highlighted using the
    autoreference mode.

    It is recommended that frame text does not take up more than the
    number of  lines  left    after  the  header  and footer have been
    allowed  for.    If  this  does    occur,    a  message  is displayed
    indicating that further text may  be  displayed  by pressing the
    PgDn key.  Also it  is possible to return to the first screen of
    a frame by pressing  the  Home    key.   Whilst frames can contain
    many  screens  full  of  data,    this   practice  is  not  to  be
    encouraged,  as  multi-screen  frames are confusing to the  user
    (Not  just  in    HyperShell  but  generally).   The  multi-screen
    support is therefore minimal, and  nowhere  near  as powerful as
    the support for paged  displays,  which  of  necessity    have  to
    support  multiple  screens.   A  formatting trigger is    provided
    which will force a 'screen break' after  the  line  in    which it
    occurred.  This is the ~G trigger.


    2.1.10.4 Notes

    Local  notes  are supplied after the text for a frame.     As  for
    global    notes  they  have  a  size  limit  of  22  lines  of  76
    characters.   They  may contain formatting control sequences and
    reference triggers, as used within the main frame text.


    2.1.10.5 Menus

    Local menus, as  for  global menus, have a limit of 22 entries.
    Each entry is supplied on  a  separate line, and consists of the
    choice    text,  and optionally  the  associated    action    for  the
    choice.  If an action string is not supplied, the default action
    is to move to the frame with a name equal to the choice text.

    An action string is separated from the    choice    text  by the '|'
    character.  If the menu is to be presented  to    the  user, it is
    good  practice to line up the  action  separator,  so  that  the
    action    type  indicator symbols line up  to  the  right  of  the
    options in the displayed menu.

    A  menu  may also be used as a lookup table, and referenced  via
    the lookup modifier (e.g. Mmenuname[key]). In this  case  it  is
    necessary  to  place  the  action  separator directly after  the
    option    text, and to always supply the action string.  If a menu



                       2-8             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    is to be used with a direct index specifier (e.g. Mmenuname(3)),
    the action string is not normally required.

    The following menu has the actions described afterwards:-



    .MENU various
    starting
    help        |Nhelp
    next frame  |F+
    exit program|Q

    The  first option, when selected, displays the frame  'starting'
    in the current hyperfile.

    The second option displays a global popup note called 'help'.

    The third option moves to the next frame.

    The fourth option quits the HyperShell program.


    2.1.10.6 Scripts

    Local scripts, as for global scripts, are limited  to  a maximum
    of 100 lines, and each    line  may  contain a number of actions.
    Script processing is cancelled when a new  frame  is  displayed,
    although remaining  actions  on  the current script line will be
    executed.

    A script  can be used to display a sequence of notes, to input a
    number    of variables to construct a command line,  or  for  many
    other more complex purposes.   A number of control actions exist
    to  allow  looping  and  conditional  branching, and  expression
    evaluation permits simple integer  arithmetic to be performed on
    variables.   These  actions  are  not  normally used outside  of
    scripts.


    2.1.10.7 End

    The .END keyword  signals  the    end  of  the  scope of the frame
    specification.









                       2-9             Version 2.5








    HyperShell          The Hyperfile      Reference Guide







    2.2 Text annotation


    In the frame text, in the text of a popup  note  and in the text
    of  a  file  displayed    using  the  'Type file' action,  control
    sequences  can    exist  to  perform   formatting   actions   when
    displaying the text, or  to  indicate  references  of  differing
    types to be highlighted in specific  ways.   The  text    may also
    contain variable substitution  sequences  referring to system or
    application variables (See the section on variables).


    2.2.1 References

    Reference control sequences have the general form:-

    ~?text string~E

    or

    ~?text string~Paction string~E

    Where ? is the reference type identifier, and text string is the
    text to be displayed, highlighted in  a manner applicable to its
    type, in  the  frame text display.  action string is an optional
    action string which will be  performed    instead  of the implicit
    action for the reference if the reference is selected.

    The reference may also have a key mapping sequence before the ~E
    sequence.   This is of the form ~Kx, where x  is  the  character
    which will be mapped to the reference on  the  keyboard.  Thus a
    reference of the form:-

    ~FNext frame~Pf+~K ~E

    will have  'Next  frame'  highlighted  as a frame reference, and
    will move to the next frame when selected  directly  or when the
    space bar is depressed.


    2.2.1.1 Frame

    The frame reference is introduced by the ~F or ~f sequence.  The
    ~F  reference  adds  the  reference  to the backtrack list, when
    selected.   The  ~f reference replaces    the  top  entry  on  the
    backtrack  list.   Thus  ~F  is  used    for  browsing  or  cross



                      2-10             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    references, and ~f is  used  for  deliberate frame sequencing or
    hierarchical   references.   The  ~f  type   of   reference   is
    highlighted  in  a  different  manner  to  tell  the  user  that
    selection  of the reference  will  not    allow  backtracking.   A
    parameter section (~P) may be added to supply an explicit action
    string to be performed on selection.


    2.2.1.2 Note

    The note reference is introduced by the ~N  or ~n sequence.  The
    ~N reference is a global note, whose specification occurs at the
    start  of the hyperfile, before the first frame  specification.
    The  ~n  reference  is    a  local  note, whose specification lies
    within the current frame specification, after the frame text and
    before the next frame.    A parameter section (~P) may be added to
    supply an explicit action string to be performed on selection.


    2.2.1.3 File note

    The file note reference is introduced by the  ~t sequence.  This
    causes a  file    with  a  name  equal  to the reference (and with
    default extension '.NTE') to be displayed as a    popup note.  See
    the 't' action for further  details.   A  parameter section (~P)
    may be added to supply an explicit action string to be performed
    on selection.


    2.2.1.4 Menu

    The menu reference is introduced  by the ~M or ~m sequence.  The
    ~M reference is a global menu, whose specification occurs at the
    start of the hyperfile,  before  the first frame specification.
    The  ~m  reference  is    a  local menu, whose specification  lies
    within the current frame specification, after the frame text and
    before the next frame.    A parameter section (~P) may be added to
    supply an explicit action string to be performed on selection.


    2.2.1.5 Script

    The script reference is introduced by the ~S  or  ~s  sequence.
    The ~S reference is a global script,  whose specification occurs
    at   the   start  of  the  hyperfile,  before  the  first  frame
    specification.     The  ~s  reference  is  a  local script,  whose
    specification lies within the current frame specification, after
    the frame  text  and before the next frame.  A parameter section
    (~P) may be added to supply an    explicit  action  string  to  be
    performed on selection.



                      2-11             Version 2.5








    HyperShell          The Hyperfile      Reference Guide





    2.2.1.6 Action

    The action reference is introduced  by    the  ~A  sequence.  This
    form of reference contains an action which is not a frame, note,
    menu or script reference.   It    covers the miscellaneous actions
    whose multiplicity precludes the use  of  specific  highlighting
    schemes.  The action  reference  always  contains  the parameter
    section (~P sequence), as it has no implicit action.


    2.2.1.7 Input field

    The input field is not exactly a reference, but is used to input
    data to be used by the application.  Its  most general use is to
    input variable values.

    The  input  field  always has reference  text  and  a  parameter
    section, which    specifies a pattern within which the input value
    is substituted prior to execution.

    The reference  text  part of the input field delimits the field,
    and provides the text which is normally displayed in the field.
    If  the  input field is  being    used  to  set  a  variable,  the
    reference  text usually contains  an  expansion  token    for  the
    variable, so that when the frame is displayed, the current value
    is  displayed  in  the field.  The field should contain a  width
    specification after any reference text, which will determine the
    width of the input field.

    The parameter section usually  consists of a variable assignment
    and sometimes some other action.  The parameter string    provides
    a pattern,  within  which  the    input value is substituted.  The
    string can  contain  up  to three occurences of the string '%s',
    each of which will be replaced by the value when it is input.

    An example of a line containing an input field is as follows:-

    Name : ~I$n~W10~PVn%s;scheckname~E

    This,  when  selected, allows a string to be entered  up  to  10
    characters in length, which is assigned to variable 'n' and then
    checked  using    local script 'checkname'. When    displayed,  this
    will look like (assuming variable n contains 'Fred Jones'):-

    Name : Fred Jones

    The input  field  may  also be specified in a note, although the
    note display will terminate after entry of the input field.



                      2-12             Version 2.5








    HyperShell          The Hyperfile      Reference Guide





    2.2.1.8 Parameter section

    The parameter section, introduced  by  the  ~P sequence, permits
    any action to be associated with a reference.  It  is usual, and
    helpful, to use the same type of action as that suggested by the
    initial introductory sequence, as it is  that  which has already
    determined  the  highlighting  scheme  for the reference.  If  a
    miscellaneous action for which there is  no set colour scheme is
    to be performed, the 'action' reference type should be used.


    2.2.1.9 Key mapping

    The key mapping sequence, introduced by ~K, permits a key on the
    keyboard to be mapped to the reference,  such  that  when  it is
    pressed, the reference is selected.   This  is useful for 'menu'
    frames.  A key mapped using the 'K' action takes precedence over
    this form of key mapping.


    2.2.1.10 Immediate reference

    One reference on a frame  display,  but  not  any  other type of
    display, may  be flagged as an 'immediate' reference, which will
    be  selected  automatically  after   the  frame  text  has  been
    displayed.  This is done by including  the sequence ~Q after the
    complete reference sequence for  the  reference to be selected.
    This may be used for many purposes, but the most common would be
    to  select  the first input field on a form frame, and therefore
    put the frame into a data  input  mode    automatically on entry.
    The immediate reference flag  may  also be used with 'invisible'
    references.   These  have a zero length reference string and  do
    not therefore permit manual selection.    This could be  placed in
    the  header or footer to, for instance,  write    a  log    file  of
    frames visited.  It can also be  used to pop up a note or a menu
    on moving to a    frame.     It may even invoke a script which could
    perform a long sequence of actions.


    2.2.2 Formatting

    The formatting sequences permit the frame, and note, displays to
    be controlled in a number of ways.  Absolute cursor  positioning
    and colour control are the main uses for this feature.

    Formatting  sequences  can be placed within the reference  text,
    provided  that    a  parameter   section     is  provided  for  that
    reference.  This facility can be used to highlight  a  letter in



                      2-13             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    the reference, if that letter key is mapped to the reference.


    2.2.2.1 Option display

    The option  display is an extended form of variable display.  It
    allows the state of various runtime  options  to be displayed as
    either    'ON'  or  'OFF'. The runtime  options  are  as    follows,
    showing the option code,  the  command    line flag and the option
    description  with  the    default state which is    toggled  by  the
    flag.


    0 -n      Create notepad file (off)
    1 -f      Symbols on menus (on)
    2 -b      Backtrack recording (on)
    3 -x      Suppress file suffix on noted frames (on)
    4 -a      Auto reference (off)
    5 -p      Select output route (off)
    6 -r      Print remaining space on exit (off)
    7 -t      Script label tracing (off)
    8 -w      Give warning when item referenced is not available (on)
    9 -l(-k)  List verbatim from 'T'action (with 8th bit stripped) (off)


    2.2.2.2 Line positioning

    The  line  positioning    command, introduced by the ~L  sequence,
    positions the text writing cursor  at the specified line, unless
    that line is before or at the current line, or beyond the end of
    the display.   The  full  form    of the sequence is either ~Ln or
    ~Lnn, where n/nn is  the  line number, starting from 1. Thus ~L3
    positions at line 3, ~L20 positions at line 20.


    2.2.2.3 Column positioning

    The column positioning command,  introduced  by the ~C sequence,
    positions  the text writing  cursor  at  the  specified  column,
    unless    that  column is before or at the  current  position,  or
    beyond the edge of  the  display.  The full form of the sequence
    is either ~Cn or ~Cnn, where n/nn is the column number, starting
    from 1. Thus ~C3 positions at column 3, ~C74 positions at column
    74.


    2.2.2.4 Width positioning

    The ~W sequence, of the form ~Wn or  ~Wnn,  is    used normally to
    specify the width of an input field (viz.). It may, however,  be



                      2-14             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    used for other purposes,  as  it  simply  specifies  a    relative
    horizontal   displacement   from  the  start  of  the    previous
    reference.


    2.2.2.5 Screen breaks

    In the frame text, a 'new page' (or  second  screen) of text may
    be forced after the current line by the  inclusion of the screen
    break  trigger.  The form of this sequence is ~G, and  this  may
    occur at any point in the line, although it is    probably easiest
    to maintain if placed at the end of the line.


    2.2.2.6 Hidden lines

    Lines in the text can be excluded from a frame or other  display
    by  putting a ~H sequence at the start    of  the  line.     The  ~H
    sequence  may be provided by a variable, which can be set to  an
    empty  string  or to ~H, depending  upon  whether  the    line  is
    required or not.  A sequence of lines can  be switched in or out
    in this manner.  The ~H sequence  can be provided literally, but
    is of limited use as such,  apart  from for embedding commentary
    information in the text.


    2.2.2.7 Text/Background colours

    The text colour and background colour can be changed  by  use of
    the ~T and ~B sequences.  The text can    have one of 16 different
    'colours' and the background can have one of 8. It is helpful to
    choose these so that they have a good contrast.  And yes, if you
    make  them  both the same, the text is invisible.  Colour  codes
    are as follows:-


    K      Black
    B      Blue
    G      Green
    C      Cyan
    R      Red
    M      Magenta
    Y      Yellow (brown)
    W      White (light grey)
    k      Dark grey    (Foreground only)
    b      Light blue    (Foreground only)
    g      Light green    (Foreground only)
    c      Light Cyan    (Foreground only)
    r      Light red    (Foreground only)
    m      Light magenta    (Foreground only)



                      2-15             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    y      Light yellow    (Foreground only)
    w      Bright white    (Foreground only)


    2.2.2.8 Display colour schemes

    The ~D sequence introduces a colour scheme selection.  There are
    26 colour  schemes,  mapped  to  the  letters A to Z. The scheme
    letter is specified  directly  after  the  ~D. The colour scheme
    sequence  works  slightly  differently    to  the  text/background
    settings  in  that  it is held over a  reference  display.   The
    available schemes are as follows, showing the scheme letter, the
    default  setting (foreground,background) and  the  normal  usage
    (items in brackets are not used by HyperShell):-


    A      wB      Action reference
    B      WK(bl)       (Blink)
    C      KY      Menu choice
    D      KW      Default title
    E      yK      Frame reference - replace backtrack
    F      wK      Frame reference - add to backtrack
    G      KK      (Ghost)
    H      KR      Menu heading
    I      yY      Input field
    J      KG      Note heading and border
    K      yG      Note
    L      RK      (Low intensity)
    M      KW      Menu reference
    N      gK      Note reference
    O      yB      Menu selection
    P      yR(bl)       Popup message
    Q      wR(bl)       (Quick)
    R      KW      Request / message
    S      yG      Script reference
    T      WK      Frame text
    U      YK      (User 1)
    V      MK      (User 2)
    W      GK      (User 3)
    X      RK      (User 4)
    Y      BK      (User 5)
    Z      rK      (User 6)

    Note that the above set is reconfigured if  -h    is  specified on
    the command line, or a monochrome display adaptor is used.

    These  schemes are configurable using the option setting  action
    'O'.





                      2-16             Version 2.5








    HyperShell          The Hyperfile      Reference Guide





    2.2.2.9 Variables

    Variables  are strings that may be stored under a single  letter
    name, either  upper  or  lower    case.    Thus  there  can  be  52
    application variables.    Variables can  be set within a hyperfile
    and may be  'expanded'    within    the  frame  text or in an action
    string.  A variable expansion  token takes the form '$x' where x
    is the variable name.  This is expanded to the string  value  of
    the variable.  If  the    '$'  symbol is required in the text, two
    '$' symbols together will  be  taken to mean one, which will not
    be expanded when the text is displayed, or when an action string
    is expanded prior to execution.  This may be used when an action
    string in a reference in frame text needs to contain a    variable
    expansion token itself, but this must  not be expanded until the
    action is performed.

    There are a number of additional variables, some of which may be
    set  by hyperfile applications,  and  some  which  can    only  be
    expanded.  The HyperShell system variables have the names '0' to
    '9' and  some  special characters, and have the following string
    values:-


    0      full pathname of HyperShell program used
    1      current frame name
    2      current frame title
    3      current file name
    4      current date
    5      current time
    6      backtrack list current depth
    7      current directory
    8      original directory
    9      HyperShell name and version
    ?      error code of last error that occurred
    <      file name returned from last paged directory display
    >      filename extension returned from last paged directory display
    :      list of filename extensions to be excluded from TYPE action
    @      Available memory
    _      File prompt (becomes null string when viewing file)
    ^      Exit status from X,x,D,d action program execution

    The ':'  variable is a string representing those file extensions
    for which  the    extended  directory  display  providing  actions
    (dynamic menu 'l') will not set a 'Type file' action.  It is set
    to the following string by default:-

    .EXE.COM.OBJ.SYS.DBF.LIB.




                      2-17             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    Additional extensions can be  added  by resetting the variable.
    Note that extensions should have a '.' to each side.

    Further applications variables called 'named variables' are also
    available, and are described under the 'l' action, below.




    2.3 Actions


    Actions are the fundamental level of control within  HyperShell.
    Action specifications can be supplied at a  number  of different
    places:-

      1.  The reference action in the text.

      2.  A menu action.

      3.  A script action.

    Not  all  forms  of  action  specification  are permitted in all
    places.   It is normally obvious  where  a  particular    type  of
    action modifier string is not applicable, or where  a particular
    action is not sensible.  In particular, control flow actions are
    only relevant in scripts (although a  popup  note  or  menu  may
    cause a branch within a currently executing script).


    2.3.1 Action tokens

    Action specifications start with  a single letter action token.
    An action may also  have  parameters supplied directly after the
    token.     The  parameters  may  be  supplied directly as  literal
    strings   or  indirectly  via  one  of    a  number   of     'action
    modifiers'.


    2.3.1.1 A - Action

    The 'A' action takes the following form:-

    Aactionspec

    This  action  is  provided to enable action modifiers  returning
    full action specifications to  be  serviced.   For  example  the
    extended directory listing modifier 'l' and the notepad  listing
    modifier 'R' both return action strings, and would be handled as
    follows:-



                      2-18             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    A@l*.*

    A@R

    Also the form 'A?Enter action' can be used to permit the user to
    enter an action specification for execution.


    2.3.1.2 a - Conditional action

    The 'a' action has the following form:-

    acxxxxxxx

    acxxxxxxxx;xxxxx;xxxxx

    Where c is a condition under which the    action    (which    may be a
    multiple  action,  as  shown in the  second  example  above)  is
    executed.  The condition letter is one    of  those  described for
    the  'j'  action  below.   This  provides  a means of specifying
    conditional actions without having to use scripts.


    2.3.1.3 B - Backtrack

    HyperShell  retains  a     list    of  frames  that  the  user  has
    displayed.  This list acts  like  a  'stack'  which  has a frame
    reference 'pushed' when a  new    frame  is  displayed.    The  'B'
    action 'pops' the frame  references  from  this  stack    one at a
    time, displaying the frame referenced.


    2.3.1.4 b - Multiple backtrack

    The 'b' action permits a  number  of frames to be discarded from
    the  backtrack    list,  retaining   the     depth    specified  as  a
    parameter, and displays the  frame  referenced    at  that point.
    This action is usually used with the 'B' dynamic menu, to permit
    the point in the list to be selected.

    b@B

    To backtrack, leaving a depth of 3 entries, the following action
    is specified:-

    b3







                      2-19             Version 2.5








    HyperShell          The Hyperfile      Reference Guide





    2.3.1.5 C - Change drive / directory

    The 'C' action allows  the  working directory to be changed, and
    optionally  allows  the  working   drive  to  be  altered.   For
    example:-

    CB:\HYPER

    CSUBDIR

    C..\HYPER2

    The original drive:directory is held  in  system variable 8, and
    the current drive:directory  is  held in system variable 7. Thus
    the   action   'P$7'   would   display     the   current     working
    drive:directory,  and  the  action  'C$8'  changes  back to  the
    original directory.


    2.3.1.6 D/d - DOS command execution

    This action starts the DOS command processor to run a command or
    to permit command line interaction.  If a parameter is supplied,
    it is issued as a command line to DOS. The  command can be a DOS
    built-in command, a batch  file,  or  an  external program.  The
    command can have parameters.

    If  the action is specified  without  parameters,  it  runs  the
    command line interpreter to allow the user to interact with DOS.
    When  the  user has finished, the EXIT command is used to return
    to HyperShell.

    The uppercase form of the action indicates that when the command
    has finished, a key press is  required    before    redisplaying the
    current HyperShell frame  again.   The    lowercase form indicates
    that when the command has finished, HyperShell will  immediately
    redisplay the current frame.   The system variable '^' is set to
    the  exit  code  of  the  DOS command processor  (although  this
    appears to be 0 always!).  If the command line contains  a space
    character  as  the first character, the screen    is  not  cleared
    before invocation and refreshed  afterwards,  allowing    'silent'
    commands,  or  commands  with  redirected output to be    executed
    without  disturbing  the display.  If the command does output to
    the screen, the display will be disturbed, but can be  refreshed
    using  the  'y'  action.   It  is preferable to ensure that  the
    command  will never output to  the  screen.   Examples    of  this
    action follow:-




                      2-20             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    D

    DDIR/W *.HYP

    d DEL DATA.DAT


    2.3.1.7 E - Command chaining

    The 'E' action    executes another program, overwriting HyperShell
    in  memory.   Only  programs (files with  .EXE    or  .COM  as  an
    extension) can be executed  using  this  action.   If subsequent
    return to HyperShell is required, either  the  'D' action or the
    'X' action should be used, although  these  will  mean    that the
    program has  less  room  in  which  to    execute,  as  HyperShell
    occupies around 102k of memory.


    2.3.1.8 e - expand variable

    The 'e' action allows a variable to be split  into  fields,  and
    assigned to a number of other variables.  It takes the form:-

    evsabc..

    Where 'v' is the name of the source variable, 's' is a character
    used to  separate the fields in the source variable, and abc...
    are  the  target  variables  to  receive  the  fields.     If  the
    character  's'    is  ommitted,  the  fields  are  assumed  to  be
    separated  by  spaces.    See the appendix for a list of    reserved
    characters which cannot be used as separators.

    The  opposite effect of this action is to store the values of  a
    number    of  variables in a variable, with  a  separator  between
    them.  This can easily be accomplished by the form:-

    Vv$as$bs$c

    Where the values of v,s,a,b,c are  as above.  This mechanism can
    be  used to pack a set    of  variables  for  storage  whilst  the
    variable  names are used for some other purpose.  Of course  the
    variable can be expanded  into a set of variables other than the
    original.


    2.3.1.9 F/f - Frame selection

    The 'F' action selects a new frame to display.





                      2-21             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    Fframename

    The parameter specifies the  frame  name  of  the  frame  to  be
    displayed.  If just a  frame  name  is    supplied,  the    frame is
    assumed to be in the local hyperfile.  If the extended form

    Fframename^hyperfilename

    is used, this indicates that the frame belongs    to the specified
    hyperfile.  The home frame of a hyperfile can  be  selected with
    the form:-

    F^hyperfilename

    Indeed the home frame of the  current hyperfile is selected with
    the form

    F

    The  lowercase    form  of   the    action    modifies  the  backtrack
    processing  so that the frame replaces the last frame  reference
    on  the  backtrack  list, rather than being added to the  list.
    This is used to step through  related  frames  when  it is clear
    that the user is reading  them    through,  and  where  it  is not
    necessary  to  stack  the  frames  on  the backtrack list.   The
    example shows an action which will step to the next frame in the
    hyperfile, without retaining the previous frame reference.

    f+

    The '+' modifier is only applicable to the 'F' or 'f' action.


    2.3.1.10 H/h - Notepad maintenance

    The  notepad,  as  well as being maintained by the INS    and  DEL
    keys, may also have  data  added  and removed by the 'H' and 'h'
    actions.   The    items  on  the notepad would normally be  action
    specifications, although it is possible to store other    data  on
    the list  for selection for other purposes.  These actions cause
    the notepad scan pointer (used by !R) to be reset.


    2.3.1.11 I - Select next input field

    The 'I' action is specific  to    frames containing input fields.
    This action is    used  in  an input field action string to select
    the  next  input  field  after    input is complete on that  input
    field.




                      2-22             Version 2.5








    HyperShell          The Hyperfile      Reference Guide





    2.3.1.12 J/j - Jump within script

    The uppercase form 'J' is an unconditional branch, and transfers
    control to the script label denoted by the parameter.

    Jstart

    Branches to the line containing 'Lstart' in the  script.  If the
    label  does  not  exist  in the script, the jump does  not  take
    place,    and  processing  continues with the  next  line  in  the
    script.

    The lowercase form 'j' is a conditional jump, and is followed by
    a letter denoting the condition upon  which  a    jump will occur,
    followed  by  the  label  to which a branch will be made if  the
    condition is set.  This 'condition' is set up  by  the    variable
    testing  action  'v'.  The  conditions available are as  follows
    (note the lowercase form MUST be used):-


         e        variable equals string          *
         n        variable not equal to string
         g        variable greater than string      *
         l        variable less than string          *
         d        variable is defined
         u        variable is undefined
         c        variable contains string
         w        variable is contained within string

    Note  that  the conditions  marked  with  an  asterisk    indicate
    lexical comparisons unless the    comparand  string  starts with a
    numeric digit or a minus sign '-',  in    which case an arithmetic
    (integer) comparison is made.

    In addition, the 'j'  action  can  be  used to test if the error
    status is set, by use of the following conditions:-


         s        jump if error status set
         o        jump if error status O.K.

    The error status can be cleared to 'O.K.' by the action 'Y', and
    will otherwise retain its  setting,  even  if successful actions
    are performed.







                      2-23             Version 2.5








    HyperShell          The Hyperfile      Reference Guide





    2.3.1.13 K - Set key mapping

    The  'K' action maps a keyboard key to an action  string.   This
    action is  then  available  from a frame display (not from paged
    displays).  When the key is pressed, the action is performed.

    Function  keys    and  printable    ascii  characters may be  mapped
    (subject    to     them    not    conflicting    with    HyperShell
    metacharacters).   The    key  to  be  mapped  is specified by the
    following notations:-




         K#xstring         Character x
         KFnstring         Function key n
         KSnstring         Shift/function key n
         KCnstring         Ctrl/function key n
         KAnstring         Alt/function key n

    Function key 10 is indicated by n = 0.

    Unshifted function keys equate to the main control menu actions,
    and mapping them changes  the  actions    for the main menu.  This
    can be used to disable certain control menu options.  The option
    text for the main menu can be set using the special form:-

    KMnstring Set menu option text n to string

    The control menu can be reset at any time by the special  option
    action

    O#

    This is useful for inclusion at the start of the SETUP script in
    a hyperfile, in case another hyperfile    has changed the settings
    in its own SETUP script.

    Mapped    strings  may  be obtained by use of the string    function
    &Mx, which returns the string mapped  to the specified character
    'x'.


    2.3.1.14 L - Label in script

    The 'L' action does  not do any processing, but indicates a line
    in a script to    which the jump actions can branch.  If the trace
    flag is switched on, the script stops at each label it executes,



                      2-24             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    showing the label name.  The label line takes the form:-

    Llabelname

    Where labelname is the    name  of the label, which may be used as
    the target of a jump statement.


    2.3.1.15 l - load named variable

    Named  variables  can be  used    instead  of  the  single  letter
    variables  to hold information for expansion in text  or  in  an
    action.  A named variable is assigned a value by the action:-

    lvnamed

    Where v is a  single  letter variable and 'named' is the name of
    the named variable.  The contents of  the  variable v are loaded
    into the variable 'named'. Note that the name can be supplied by
    an action  modifier  or  by  the  expansion of a variable token,
    including that of the same or another named variable.

    Named variables are expanded using the form:-

    $(named)

    and the name can  again  be  specified    by  an    expansion token,
    although  in  this  case  this    can  only  be  a  single  letter
    variable.  e.g.

    $($n)

    Where n is  a  single letter variable containing the name of the
    named variable.  This feature  can  be used as a limited form of
    'subscripting', or indirection.


    2.3.1.16 M/m - Popup menu display

    This action performs the action resulting from selection  by the
    user from the named menu.  The uppercase form is used for global
    menus and the lowercase form for local menus.

    Mmenuname

    A menu action, and a menu  action  modifier,  may  have  special
    modifiers added to select  from  the  menu  by    means other than
    interaction.  The following form is used to select a menu choice
    by index:-




                      2-25             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    Mmenuname(nn)

    Where nn is a number representing the option number in    the menu
    to  select.  If the number is outside the range of the menu,  no
    action is performed (or returned  for  an  action modifier), and
    the error status is set.

    A menu can also be used as a lookup  table.   The  menu  is then
    accessed by a specification of the form:-

    Mmenuname[key]

    In this case, the lines in the menu section have to be set up in
    the following form:-

    key|action

    Where key is the key to  look  up,  and  action is the action to
    perform  if  a    match  is  found.   The  '|'  character  has  to
    immediately follow the key string for  this to work.  If the key
    is not found in the menu, no action  is  performed and the error
    status is set.    If the key is found, the action part is returned
    as the menu result.


    2.3.1.17 N/n - Popup note display

    The  action  'N'  pops    up  the  named    note,  and waits  for  a
    key/button press before clearing  the  note.  The uppercase form
    applies to global notes  and the lowercase form applies to local
    notes.     Notes    can  contain  references  just as frames do, and
    these will be actioned if selected.

    Na note


    2.3.1.18 O - Option setting

    The  action  'O'  is  used  to set HyperShell control flags  and
    colour schemes.   A  numeric  option sets a run control flag, an
    alphabetic option sets a  colour  scheme.  The control flags are
    set  to  0  for  OFF   or   1    for   ON.   This   example  sets
    autoreferencing:-

    O41

    An option can be 'toggled', that is set off if on and set on  if
    off,  by  specifying  an  alphabetic  value.   E.g.  to   toggle
    autoreferencing:-




                      2-26             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    O4T

    The colour schemes are set to  a  two  character  colour setting
    consisting of the foreground  and background colours.  Note that
    the brighter 8 colours cannot be used for the background.   This
    example sets note references to be bright yellow on dark green:-

    ONyG

    A special option setting is used  to  reset  the control menu to
    its default values:-

    O#


    2.3.1.19 o - Printer output

    The 'o' action prints the supplied  string  to a route specified
    by the printer option.     The  valid  values,  along  with  their
    routes, are as follows:-

    0 - Display on bottom line

    1 - Print to printer

    2 - Send to standard output

    3 - Send to standard 'AUX' (e.g. RS232)

    4 - Send to 'output file' (that opened by action 'w')

    If  an    invalid  route    is specified, output goes to the  bottom
    line.  The printer is enabled by using '-p' on the command line,
    or by issuing the action 'O51' to  set    option    5  to 1. The 'o'
    action adds a carriage    return and a line feed character to each
    line supplied.

    oListing of items

    To  output  a control code to the printer, such as a form  feed,
    the string function &Cnn can be used:-

    o&C12

    Other routes are set using the O5n form, which sets the route to
    'n', where n is one of the above.







                      2-27             Version 2.5








    HyperShell          The Hyperfile      Reference Guide





    2.3.1.20 P - Popup message

    The 'P' action pops up a flashing  message  at the current mouse
    cursor    position,  and    awaits    a key/button  depression  before
    'popping down'.

    PHello there!

    If  a null string is passed as a  parameter,  an  asterisk  will
    flash in the bottom right hand corner of the screen.   This  can
    be  used  as  a  pause    to await a key depression from the  user
    before continuing with a series of actions.


    2.3.1.21 p - Print message

    The 'p' action prints a message at the bottom of the screen, and
    continues without waiting for any inputs.

    pThis is a long message to stay on the screen


    2.3.1.22 Q - Quit HyperShell

    This  action  is  used    to  exit  the HyperShell program.  If  a
    parameter string is given, its numeric value is used as the exit
    status    for the HyperShell program.   This  means  you    can  use
    hypershell in batch  files to control the flow, just as with the
    'ask', 'choose'  etc.  type programs that set the exit status to
    be  tested  with  the  'IF ERRORLEVEL' statement.   It    is  also
    possible  that    you may wish to return information to a  program
    that has invoked HyperShell directly.


    2.3.1.23 q - Quit script

    This action cancels any  current  script being executed.  It can
    be used to abort a script if an error status occurs.


    2.3.1.24 R - Formatted read

    The  'R'  action  allows  a line to be read from the input  file
    (opened via the 'r' action), split  into fields, and assigned to
    a number of variables.    It takes the form:-

    Rsabc..




                      2-28             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    Where 's' is a character used to  separate  the  fields  in  the
    input  line,  and  abc...   are  the  variables to  receive  the
    fields.  If  the  character  's'  is  ommitted,  the  fields are
    assumed  to be separated by spaces.  See the appendix for a list
    of reserved characters which cannot be used as separators.

    When  the  end    of  the file  is  reached,  no    assignments  are
    performed and the error status is set.


    2.3.1.25 r - Open/close input file

    This action  is  used  for  opening  or  closing  an  input file
    dedicated to applications use.    If a  parameter  is supplied, it
    contains the name of  a file to open for input.  If no parameter
    is supplied, the input file is closed.    The file opened via this
    action can be read  by    the action modifier '!' or by the action
    'R'.  Note that on opening an input file, any already open input
    file will be  put  in  suspension  until  the file is closed, at
    which  time  the  original  file  will again  be  available  for
    reading.  There can only be two suspended input files.


    2.3.1.26 S/s - Execute script

    The  'S'  action  executes  a named  script.   If  a  script  is
    currently  being  executed,  it is cleared prior to running  the
    specified script.

    The uppercase form refers to a global script, the lowercase form
    to a local script.


    2.3.1.27 T - Type file

    The 'T' action presents a paged display of the named text file.
    If no  parameter is supplied, reentry to a file display that has
    been interrupted is assumed.   The  paged display highlights any
    references  embedded  in the text file, allowing an  alternative
    hypertext  structure.  Autoreferencing can also be used to  good
    effect, where for instance the current hyperfile contains frames
    named with topic which are mentioned in the file being browsed.
    For instance, if an MSDOS help hyperfile is being used, any file
    containing references to the  MSDOS  commands  will  have  those
    references  highlighted  as frame references,  selection  of  an
    applicable frame is then possible, followed by further hyperfile
    browsing prior to return to the file browsing.

    Option 9 switches off reference highlighting (and strips 8 bit).

    A number of control  keys  are    supported  during the paged file
    display.  The PgDn key    may  be used to move to the next page of

                      2-29             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    text.  The PgUp key may be used to move  to the previous page of
    text.    The  Home key will move back to the start of the  file.
    The '#' key will prompt for a page number, and will move to that
    page,  if present.  The '/' key will prompt for a search string,
    and search forward through the file for that string, stopping at
    the page containing the string and highlighting  the line within
    which the string was  found.   The  End  key terminates the file
    display, without cancelling any script that is in progress.  The
    ESCAPE cancels the file display, along with any current script.
    The RETURN key returns to the current frame display, and permits
    viewing of the file to continue by use of the 'T' action with no
    parameter.   A    further  T  action, supplying a parameter,  will
    cancel the current file display and start a new one.

    The function keys can also be used  during  this display and are
    mapped as follows:-


         F1   Help
         F2   Go to page
         F3   Previous page
         F4   Go to start
         F6   Search for string
         F9   Suspend typing
         F10  Exit typing


    2.3.1.28 t - file note

    The 't' action displays the contents of a file as a popup note.
    The note contents can be as for the 'n' and 'N' actions, and can
    contain references which can be selected.  The file note is used
    for a number of purposes, and usually indicates that the note is
    less  permanent than one included in the hyperfile.   It  could,
    for  instance,    be  a scratchpad note created by the  HyperShell
    user.


    2.3.1.29 V - Set variable

    The  'V'  action allows a variable to  be  set.   There  are  52
    applications variables    named  'a'  to 'z' and 'A' to 'Z'. There
    are a few  system  variables  that may be set using this command
    also, although the numeric ones cannot be changed.  The variable
    is set to the value supplied as a parameter:-

    Vxstring

    Sets the variable 'x' to the value 'string'.  Variables can hold
    any string value,  and    can  also hold numeric data as a numeric



                      2-30             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    string.  Variables can    be expanded into the frame text display,
    a note display, or into an  action  string,  by  specifying  the
    variable substitution token '$x' where x is the variable name.

    The 'named' variables described  under the 'l' action may not be
    set using this action.


    2.3.1.30 v - Test variable

    All single letter variables can be tested using the 'v' action.
    The specification of a 'v' action is:-

    vxstring

    Where x is the variable name and string is the string to perform
    a comparison against.  A lexical comparison is performed, unless
    the comparand  string  starts  with  a    numeric digit or a minus
    sign,  in  which case an integer numeric comparison is made.   A
    substring  search  of  both  operands  within  each other.   The
    resulting condition codes are used in the 'j' action.

    To  test  a  named  variable,  it first has to be loaded into  a
    single letter variable.


    2.3.1.31 W - Write record to file

    The 'W'  action  writes  the parameter string to the output file
    opened via the 'w'  action.   A line can be formatted to contain
    the  values  of variables  by  simply  specifying  the    variable
    expansion tokens at the  required  place  in  the line.  Thus to
    write a line with variables  a,b,c in it separated by colons, we
    specify:-

    W$a:$b:$c


    2.3.1.32 w - Open/close output file

    This action is used  for  opening  or  closing    an  output  file
    dedicated to applications use.    If  a  parameter is supplied, it
    contains the name of a file to open for output.  If no parameter
    is supplied, the output  file  is  closed.   The file opened via
    this action can be written to using the 'W' action.  If the file
    cannot be  opened, an error status is set.  Note that on opening
    an  output  file,  any    already open output file will be put  in
    suspension until the file is closed, at which  time the original
    file will again be available for writing.  There can only be two
    suspended output files.



                      2-31             Version 2.5








    HyperShell          The Hyperfile      Reference Guide





    2.3.1.33 X/x - Execute program

    The 'X' action executes the  program  and parameters supplied in
    the parameter string, and returns to HyperShell when the program
    terminates.  The uppercase form waits for  a  key  press  before
    redisplaying  the  current frame,  the    lowercase  form  returns
    immediately to the display.   The  system variable '^' is set to
    the numeric exit code of the program.

    Care should be exercised when specifying the program invocation,
    as  certain  errors  will  'crash'  the computer and  require  a
    reboot.  If in doubt, use the 'D' action, which is safer.  The X
    actions are more efficient  in    speed  and  memory  utilisation,
    however, and the exit code of the program is always available.


    2.3.1.34 Y - Null action

    The  'Y' action does nothing, apart from reset the error  status
    to 0.  It  is also used to 'throw away' the results of an action
    modifier.


    2.3.1.35 y - refresh frame display

    The 'y' action    refreshes  the    current  frame    display.   If  a
    parameter is  supplied,  and  the  frame  occupies more than one
    screenful, the next screen of the frame is displayed.


    2.3.2 Action Modifiers

    The action may have its parameter string supplied indirectly via
    an action modifier, or the first character supplied directly and
    the  rest  supplied indirectly.  The  action  modifier    argument
    string    may contain variable tokens, which are expanded prior to
    evaluation.  The result of the action modifier can optionally be
    further formatted via a pattern string.  The resulting parameter
    string then has any variable token specifiers expanded prior  to
    being applied to the action.  Action modifiers are as follows:-


    2.3.2.1 Prompts

    The modifier form for a prompt is

    ?prompt string




                      2-32             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    Where prompt string is a string which  will  be  output  to  the
    user.    The input response will form the actual  parameter.   If
    the first character of the prompt is a ':', the response is  not
    echoed to the user,  allowing  passwords  and other confidential
    material to be input.


    2.3.2.2 Input file

    A number of file  input  facilities  are available for the input
    file (that file opened by an 'r' action).  The    modifier  for  a
    file read is

    !F{key}

    Where {key} is an optional key string, which is compared against
    the start of each record read  until  a  match    is  found.   The
    comparison  is case insensitive.  If '!' or '!F' appears on  its
    own, it  returns  the  next  line read from the input file.  Any
    search    starts    immediately  after  the  last record read.   The
    modifier

    !L{key}

    Causes the file to be rewound prior to the search taking place.
    The EOF status is set if the end of file  is  reached for any of
    these modifiers.


    2.3.2.3 Noted references

    The noted references, set up  using  the  INS  key  or    the  'H'
    action, can be obtained using the modifier

    !R{key}

    The {key}, if present, causes the  references  to be scanned for
    the next one starting with the key string.  For example:-

    !RF

    returns the next frame reference.

    Any  search  or  step  is  taken  from after the last  reference
    obtained.  The scan pointer is reset  whenever    a  reference  is
    added or removed from the list, and can  be rewound with a dummy
    'remove' action:-

    h




                      2-33             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    The  EOF  status  is  set when the  end  of  the  references  is
    reached.


    2.3.2.4 Environment Variables

    An environment variable modifier takes the form:-

    %variablename

    Where variablename is the name of a DOS  shell variable, set via
    the SET command under  DOS,  whose  value  will  form the actual
    parameter.


    2.3.2.5 Expression evaluation

    An expression evaluation modifier takes the form

    =expression

    Where expression is an    integer  expression involving the simple
    arithmetic operators +,-,*,/ and parentheses to direct order  of
    evaluation.   The expression  can  involve  integer  values  and
    alphabetic variable names (used directly without the $    token).
    The  expression  must  not  contain  any  embedded spaces.   For
    example to calculate a value and assign it to the variable 'c':-

    Vc=(22*r*2)/7

    Four byte signed integers  are    used  in  the  evaluation of the
    expression.

    The condition flags are set  after  an    expression evaluation as
    though    the  result  had been compared against zero.  Thus if  a
    negative  result  needs  to  be  tested, the condition flag  'l'
    should be used.


    2.3.2.6 Functions

    There  are  a  number  of  functions  which return a string or a
    number.  The function modifiers 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
    functions are as follows:-




                      2-34             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    The 'L' function returns the length of the remaining text string
    in the action, and is the same as the BASIC LEN() function.

    &Labc returns '3'

    The 'A' function returns the ASCII value of  the first character
    of  the remaining string, and is the same  as  the  BASIC  ASC()
    function.

    &AA returns '65'

    The 'I' function takes the next character as  a search argument,
    and returns the  index    of  this  character within the remaining
    string, or zero if it is not found.   This  is    similar  to  the
    BASIC INSTR() function, but only deals with a  single  character
    search argument.

    &Icabcdef returns '3'

    The 'C' function returns the character    equivalent  to the ASCII
    value provided by the remaining string, which is expected to  be
    numeric, and is the same as the BASIC CHR$() function.

    &C66 returns 'B'

    The 'N' function takes the next character as a numeric    argument
    specifying  an index into the string.  The character indexed  in
    the string is returned as the result of the function.

    &N4abcdef returns 'd'

    The 'S' function takes    the next character as a numeric argument
    specifying an index into the string.  The substring  indexed  in
    the string  is    returned as the result of the function.  This is
    similar to a variant of the BASIC MID$() function.

    &S4abcdef returns 'def'

    The 'U' function takes the next character as a search  argument,
    and returns the substring up to, but not  including, the located
    character, or a null string if this is not found.

    &Udabcdefg returns 'abc'

    The 'F'  function takes the next character as a search argument,
    and  returns  the  substring  from,  and including, the  located
    character, or the full string if this is not found.

    &Fdabcdefg returns 'defg'




                      2-35             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    The 'T' function takes the remaining string as a frame name, and
    returns the title string for that frame.

    &Tstart could return 'initial frame'

    The  'M'  function takes the next character as a key  character,
    and returns the string mapped to  that    character (using the 'K'
    action), or a null string if nothing is mapped.

    &Mh could return 'NHelp'

    The 'K' function takes the remaining string as a popup    message,
    awaits    a key depression, and returns the character for the  key
    pressed.  This is similar to the BASIC INKEY$() function.

    &KPress Y or N could return 'Y' or 'N'


    2.3.2.7 Dynamic menus

    The dynamic menu modifier takes the form:-

    @menuspec

    Where  menuspec  is one of the    available  dynamic  menus.   The
    selected  choice  from    the  dynamic  menu  becomes  the  actual
    parameter to the action.

    Dynamic menus available are:-

      1.  Backtrack list (returning level number)

      2.  Current Hyperfile contents list

      3.  Directory listing (extension stripped)

      4.  Directory listing (with extension)

      5.  Directory listing (directories only)

      6.  Contents of file as popup menu

      7.  Extended directory display

      8.  Extended directory display with actions added

      9.  Global/local menu - resulting choice

      10. Global/local/file note - resulting selection




                      2-36             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



      11. Reference notepad paged display

      12. Search for string in titles of current hyperfile

      13. Search for string in titles of visited hyperfiles

      14. Search for string in titles and texts of current hyperfile

      15.  Search  for  string  in     titles  and  texts  of  visited
          hyperfiles

    The various dynamic menus are described in a separate section.


    2.3.2.8 Pattern strings

    The  pattern  string may be optionally specified after an action
    modifier to format the returned value into a  form  expected  by
    the action.  Pattern strings consist of the string expected as a
    parameter, with all occurences of the chosen string  represented
    by the string '%s'. Up to three occurrences of the chosen string
    may be expanded in the pattern    string.  An example is a command
    to copy a  file  selected  from  a directory display to the root
    directory of drive C:-

    d@d*.*|COPY %s C:\%s


    2.3.2.9 Multiple actions

    Multiple  action specifications can exist in an action    string.
    The action  specifications  are  separated  by    ';' characters.
    Multiple actions are allowed wherever an action specification is
    expected.




    2.4 Dynamic menus


    Dynamic  menus supply the parameter to an '@' action  modifier.
    These menus  are  not  necessarily  'dynamic', but the term does
    apply to some  of  them,  and  is  used  collectively for all of
    them.  These menus come in three types:-








                      2-37             Version 2.5








    HyperShell          The Hyperfile      Reference Guide





    2.4.1 Paged displays

    Paged displays provide    a  full screen display offering one line
    per   option,    and  offering  multiple  pages    of  options   if
    necessary.   Paged displays allow forward (and backward in  some
    cases)    pageing,  and  either  direct  selection,  or  reference
    'noting' using the INS and DEL keys.  The  various  paged  menus
    are described here.


    B          Backtrack list as menu (returning level number)
    C          Current Hyperfile contents list as menu
    Lwildspec      Extended directory display
    lwildspec      Extended directory display with actions added
    R          Reference notepad paged display
    Sstring       Search for string in titles of current file
    sstring       Search for string in titles of open files
    Xstring       Search for string in titles and texts of current file
    xstring       Search for string in titles and texts of open files

    The backtrack list menu  returns the backtrack level number, and
    is usually used with the 'b' action.

    The current contents menu returns a  frame selection action, and
    should be used with the 'A' action.

    The search menus normally return a  frame  selection action, but
    may  also  return other reference actions.  They should be  used
    with the 'A' action.

    The notepad display returns  reference    actions,  and  should be
    used with the 'A' action.

    The extended directory display returns a filename, and should be
    used in an action requiring a filename as a parameter.

    The extended directory display    with  actions added provides its
    own action strings  for  typing  a  text  file    or changing to a
    directory, and should be used with the 'A' action.


    2.4.2 Simple menus

    Simple menus appear as 'popup' menus.


    Dwildspec     Directory listing (extension stripped)
    dwildspec     Directory listing (with extension)



                      2-38             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    Ewildspec     Directory listing (directories only)
    Ffilename     Contents of file as popup menu
    M(or m)name     Global/local menu

    The directory listings return  the filename, with or without the
    file extension.

    The  file  contents  menu  returns  the  result  for  the choice
    selected as defined in the file.   The    file  should contain the
    same textual content as a normal menu section  (with  or without
    separate actions).

    The  normal menus  return  the    choice    itself,  or  a    separate
    'action', if specified.


    2.4.3 Other types

    The other types are

    N(or n or t)name Global/local/file note

    This returns the 'parameter'  resulting  from the selection of a
    reference in the text of the displayed note.




    2.5 Variables


    A  number of string variables are provided to allow a  hyperfile
    to  modify  its  behaviour   depending    on  circumstances.   For
    instance, variables  may  be  used  to input parameters one at a
    time  in  order  to  build up a command line for execution under
    DOS,  or  to  build  an  action specification.    Popup menus  are
    useful for setting variables to one of a fixed set of values.


    2.5.1 Variable assignment

    Variables are assigned using the V action.  The assignment takes
    the form:-

    Vxvalue

    Where  x represents any upper or lower case letter, which is the
    variable  name, and value represents the value to assign to  the
    variable.   The  normal action string assigns a constant  value,
    and action modifiers are used to supply variable  values for the



                      2-39             Version 2.5








    HyperShell          The Hyperfile      Reference Guide



    variable.  For example,  the  value may be chosen from a menu or
    input from the user via a prompt.


    2.5.2 Variable substitution

    The variable may be expanded in the frame  text, in a note text,
    or in an action string, where it may form any part of  an action
    string    apart  from the action token itself  (although    the  'A'
    action can be used to permit the expansion  of    a variable to an
    action token).

    The variable  expansion specifier is simply the flag character $
    followed by the variable name character.  e.g.    :-

    $a

    Further variables called 'named variables'  are  available,  and
    are described under the 'l' action.




    2.6 Alternative hypertext


    The HyperShell hyperfile format described above is normally used
    for hypertext systems.     HyperShell  does,  however,  provide  a
    number of features which support an alternative to this format.

    The 'T' and 't' actions,  described  above,  permit  normal text
    files to  be  displayed,  and  these  files  can  contain simple
    embedded  references  to  other  files,  for display in a  paged
    fashion  using 'T' or as a popup note using 't'.  The  authoring
    guide gives a description of how this can be done.

    If  HyperShell    is  given  the name of one of these simple  text
    files, rather  than  that of a normal hyperfile, it displays the
    file as a single frame, possibly with multiple pages.  Thus,  it
    is not even necessary to have a controlling hyperfile.    Although
    it  would  not    be  usual  to  do so, such a file could  contain
    HEADER, FOOTER and global  items,  provided  these were supplied
    AFTER the main text in the file.










                      2-40             Version 2.5








    HyperShell          The Hyperfile      Reference Guide







    2.7 Limits


    2.7.1 sizes

    Line size,  including  flag characters, expanded variables etc.
    is limited to 255 characters.

    Frame name may be up to 30 characters.

    Title length may be up to 40 characters.

    Reference text length may be up to 40 characters.

    Action strings may be up to 40 characters, or 79 in scripts.

    Frame text can be up to 79 characters wide.

    Frame  text  can  be  any  number  of lines  deep  although  the
    recommended limit is 24 - (header lines + footer lines).

    Note  text  can  be up to 76 characters wide and 20 lines  deep,
    extra text being truncated.


    2.7.2 numbers

    There  can  be    up  to    100  references  per  displayed  screen,
    including headers and footers, and any note popped up containing
    references.

    A menu can be up to 22 entries.

    A script can contain up to 100 actions.















                      2-41             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide









                    Chapter 3

                HyperShell Editor




    3.1 Introduction


    The HyperShell editor  allows  new  hyperfiles to be created and
    existing  hyperfiles to be edited.  It permits the structure  of
    the hyperfile to be edited, as well as the  textual  content  of
    the  items held within the hyperfile, in a  manner  common  with
    some outline processors.




    3.2 Invocation


    The editor is invoked from the DOS prompt with a command line of
    the following form:-

    HE {flags} hyperfilename {outputfilename}

    Where 'flags' are command line flags of the form

    -x -y -z

    and have the following meanings:-

    The  -c  flag  is  used when a file is to be created.  A warning
    message is  otherwise  output  to  say    that  the file cannot be
    opened.  When a file is created, a single  frame  is  created to
    permit the editor to load  the    file.    This  frame can have its
    name and title changed as required.

    The -s    flag  causes the contents of the screen at invocation to
    be saved for redisplay upon exiting the editor.

    The  -n flag indicates that a backup file is not to be    retained
    after the editor exits.



                      3-42             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



    The -m flag causes the editor to attempt to use the mouse driver
    directly.

    The -r flag causes the remaining memory to be displayed prior to
    exit.

    The -d flag causes BIOS calls to be  used  for    screen    update.
    This option should only  be  used  for    non-compatible computers
    that do not have the screen mapped in a conventional way.

    The -h flag indicates that an alternative highlighting scheme is
    to be used, for support of  MDA  and  Hercules    adapters, and is
    used if the program does not detect that a monochrome adaptor is
    in use.  This also causes the mouse cursor  to    flash  if -m has
    not been specified.

    The -g flag causes the default    highlighting scheme to be used.
    It is used if the program falsely detects a monochrome monitor.

    The  -z  flag  causes  the  emulation  mouse  cursor  to  flash,
    permitting it to be spotted more readily.

    The  'outputfilename'  parameter  is  optional,  and if  present
    indicates  that  the  output of the editor is to go to the  file
    specified, rather than to the original file name.

    The TEMP environment variable  may be set to indicate the device
    and directory path to be used for the temporary file.  It speeds
    up the save and exit processes if this    is  on a different drive
    to  the original file.    Sufficient space must  be  available  to
    accommodate the temporary file,  which    will  be as large as the
    edited    file.    The  COMMAND.COM  file    must  be  available  and
    specified using the COMSPEC environment variable.

    The 'hyperfile' parameter indicates the name of the hyperfile to
    be edited, and has a default extension of '.HYP'.




    3.3 Editor processing


    An  index  is  built  in  memory for the items contained in  the
    hyperfile.   When  an item is edited within the  hyperfile,  the
    text  for the item is read from the original  file,  edited  and
    stored in memory.  When the editor is exited,  the  changes held
    in  memory are merged with the original  file,    replacing  those
    items that have been edited, ignoring those items that have been
    deleted,  inserting  new  items  that  have  been  created,  and



                      3-43             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



    reordering the items to  the  sequence    specified  in  the  item
    list.    The  merged file is produced with an extension of  .TMP,
    and if the file is successfully written, the original is renamed
    to have a .BAK extension and the temporary file renamed  to have
    the  original  name.   If  the temporary file  has  a  different
    pathname, it  is  copied  to  the  original  filename  and  then
    deleted.

    It is important, therefore, to ensure that there  is  sufficient
    space on the disk to hold the edited copy of the file as well as
    the backup.  If the temporary file is created on another  drive,
    and no backup is retained,  just  the  additional space required
    for  additional  items    needs  to be available on  the    original
    drive.    If the temporary file is created on the same drive, when
    the save operation is performed there will  be    a  lot    of  disk
    activity,  which  may seem alarming at first, particularly on  a
    large file.




    3.4 Editor interaction


    There are three types of display that the editor uses, these are
    the normal  frame  display,  from  which frame navigation can be
    carried out, paged displays from which    frames    or  items can be
    selected for display or editing, and the  editor display, within
    which the text is edited.




    3.5 Frame Navigation


    The  text  editor  initially  displays    the first frame  in  the
    hyperfile.  The text for the frame  is displayed, along with any
    header and footer text.  From this point, a number of directions
    are possible.  Frame references  can be selected, as they can be
    in  HyperShell,  and  will   cause  the  selected  frame  to  be
    displayed.  A backtrack list is not maintained in the editor, so
    retracing of steps is not  possible.   Other  references have an
    action    depending  on  type.   Note, menu and script  references
    cause a menu of options to be presented, allowing the referenced
    item  to  be  viewed, edited or checked for  existance,  or  the
    reference to be displayed literally or 'explained'. Other  types
    of reference just cause the reference string to be explained.





                      3-44             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



    The editor also supplies two direct frame selection mechanisms -
    the  contents list and the text  search  list.     These    work  as
    within    HyperShell,  and  provide 'paged displays' from which  a
    frame reference selection can be made, resulting  in  the editor
    moving to the selected frame.


    3.5.1 Control keys

    The  following    control keys  are  available  during  the  frame
    display:-

    CURSOR KEYS    MOVE  CURSOR   -  The cursor keys can be used to
            move the mouse cursor, as can  the  mouse if one
            is connected as required.

    RETURN        SELECT   -  The  return  key  (or the left mouse
            button)  has  the  effect,  as in HyperShell, of
            selecting a highlighted frame reference, if  the
            mouse  cursor  is  positioned over one.  If  the
            mouse  cursor  is not positioned  over    a  frame
            reference, the key press is ignored.

    TAB        NEXT REFERENCE - This moves the mouse  cursor to
            the  next   reference    in  the  frame    display,
            wrapping around to the first when it reaches the
            last.    Note  that  not all references    will  be
            frame  references,  and therefore  not    all  are
            selectable.

    SHIFT TAB    PREVIOUS REFERENCE - This moves the mouse cursor
            to the previous reference in the  frame display,
            wrapping around to the    last when it reaches the
            first.

    ESCAPE        The  escape key  (or  the  right  mouse  button)
            causes the main  control  menu    to appear.  This
            menu  permits    selection   of    certain  general
            control functions,  and is described below.  The
            options  on  the  menu may be selected with  the
            mouse cursor,  or by depression of the indicated
            function  key.    The actions associated with  the
            control menu options are  as  described  for the
            function keys below:-

    FUNCT KEY 1    HELP - This causes the    main  HELP  menu  to  be
            displayed, and permits selection from this.

    FUNCT KEY 2    CONTENTS - This  causes  a  paged display of the
            frames contained  in  the current hyperfile, and



                      3-45             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



            permits selection of a frame for display.

    FUNCT KEY 3    SEARCH    FRAMES- This option prompts for a search
            string, and then searches the  frame  texts  for
            the string, presenting a list of matching frames
            in a paged display,  and permitting selection of
            one of these for display.

    FUNCT KEY 4    EDIT THIS  FRAME  - This causes the text editing
            mode  to  be  entered to edit the current  frame
            text.

    FUNCT KEY 5    GLOBAL ITEM LIST - This presents a paged display
            of all global items, including the frames in the
            hyperfile,    and   permits   various     editing
            activities to  be  performed  upon  the list and
            upon selected items.

    FUNCT KEY 6    LOCAL ITEM LIST - This presents a paged display
            of items local to the current frame, and permits
            various editing activities to  be performed upon
            the list and upon selected items.

    FUNCT KEY 7    DOS SHELL - This causes a 'DOS Escape' whereby a
            DOS  command  line   is   presented   permitting
            operations  to    be  performed  outside    of   the
            editor, and  allowing  subsequent  return to the
            editor by use of the 'EXIT' command.

    FUNCT KEY 8    SAVE / CHECK - This causes the current state  of
            the edited hyperfile to be saved to a  temporary
            file,  and  optionally    permits  the  HyperShell
            check  program    to be run on the saved file.  If
            no  edits  have  been  performed,  a message  is
            issued and the save is not done.

    FUNCT KEY 9    QUIT -  This option causes the HyperShell editor
            to quit, without saving any edits.  A warning is
            issued    if  edits  have   been     performed,  and
            confirmation is sought before quitting.

    FUNCT KEY 10    SAVE AND EXIT  -    This causes any edits to  be
            saved to  a  new  file with the same name as the
            original (unless the -n option was supplied upon
            invocation).  The  original file is renamed with
            an extension of .BAK,  unless  the -n option was
            supplied  on  invocation,  in  which case it  is
            deleted.  If no edits have been  performed,  the
            editor simply quits without attempting to update
            the original file.



                      3-46             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



    SHIFT FKEY 1    ADD NEW FRAME  -   This causes a dialogue to  be
            entered requesting  frame  name  and  title, and
            presents  the frame for editing to permit  input
            of the frame text.

    SHIFT FKEY 2    ADD LOCAL NOTE  -  This causes a dialogue to  be
            entered  requesting  the name of the local note,
            and enters  edit  mode to allow the note text to
            be input.

    SHIFT FKEY 3    ADD LOCAL MENU - This  causes  a  dialogue to be
            entered requesting the name  of  the local menu,
            and enters  edit  mode to allow the menu text to
            be input.

    SHIFT FKEY 4    ADD  LOCAL SCRIPT - This causes a dialogue to be
            entered requesting the name of the local script,
            and enters edit mode to allow the script text to
            be input.

    SHIFT FKEY 5    CHANGE DETAILS  -   This causes a dialogue to be
            entered requesting the revised name and title of
            the current frame, and permits the current value
            to  be    taken    as   default.     The   frame  is
            redisplayed after the change is made.

    PAGE DOWN    NEXT SCREEN  -    If  the frame occupies more than
            one screen, this key moves to the next screen of
            the frame, otherwise it does nothing.    When the
            final screen has been shown, the first screen is
            reshown.

    HOME        FIRST  SCREEN  - If the frame occupies more than
            one screen, this key  moves  to the first screen
            of the frame, otherwise it does nothing.


    3.5.2 Control menu

    The control menu offers  the  options  described  above  for the
    function keys and the shifted function keys.


    3.5.3 Help menu

    The main help menu offers the following choices:-

      -  F1 - GENERAL INFO





                      3-47             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



      -  F2 - FRAME DISPLAY

      -  F3 - EDIT/VIEW MODE

      -  F4 - PAGED DISPLAY

    The  general  information  option gives  information  about  the
    current editing session, including the amount of memory left for
    edited items, and the number of edits that have been performed.

    The  frame  display  option gives information about the  control
    keys available during the frame display mode.

    The  edit and view mode option presents the  editing  /  viewing
    help menu, which is described below under the section describing
    the text editor.

    The paged display option gives the help text associated with the
    paged displays.




    3.6 Text editing


    The text editing screen is displayed  whenever an edit operation
    is  selected.    This  presents    the  text  for editing using the
    keyboard for text input and control commands.

    For most items the  text  is contained within one screenful, but
    in some cases more  than  one screen is required, and a facility
    is offered to page down and up the text in part pages.

    References, tabs and horizontal formatting controls are  handled
    in the main display to    give  the  appearance the text will take
    when displayed in HyperShell. The current line,  being that over
    which the cursor is placed, is also displayed at the  bottom  of
    the screen in its  'raw  text'    form,  as  it  is  held  in  the
    hyperfile.

    In the    case  of  menus, scripts and remarks, no highlighting or
    formatting is expected.   Nevertheless,  the same display format
    is used.

    The bottom line of  the  display  shows the type and name of the
    item being  edited,  the  current  page number and the number of
    pages.    A 'page' in this case is the screenful of text displayed
    by the editor, and most likely will not match the page number of
    a multiple screen frame display.



                      3-48             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



    The bottom  line  is  also  used to display any warning messages
    issued as a result of limits being exceeded  etc.   It    is  also
    used  to display the overwrite mode when this is in  effect,  to
    indicate  when a function key macro is being  recorded,  and  to
    indicate when the symbol shift is in effect.


    3.6.1 Moving around

    The  cursor  keys  are    used to move around the text, and permit
    character, word, line and  page movement in both directions.  If
    a mouse is mapped to the cursor keys, this may also be used  for
    moving around,    although  you  may  find  that    it  is difficult
    positioning with the mouse in edit mode.


    3.6.2 Inserting text

    Text  is  inserted  at    the  current  cursor  position by typing
    characters.   An  OVERWRITE mode  may  be  toggled-in  to  allow
    existing text to be overwritten.  The RETURN (or NEWLINE) key is
    used to start a new line (or to split a  line  if  the cursor is
    positioned within a line).  The TAB  key inserts a tab character
    in the current position,  and  uses  this to tab to the next tab
    position, which occurs on the next 8th character boundary.

    Control  characters, other than tabs, are not inserted, nor  are
    decimal  codes above 159  entered  via    the  ALT/Numeric  keypad
    keys.  Any key, including  a  control  key,  can  be inserted by
    preceding  it  with  a    Ctrl-Q key press,  although  caution  is
    advised when doing this.

    Special symbols, with codes above  decimal  159,  are entered by
    use of a special 'symbol shift' which is toggled using    Function
    Key 8.    When  the  symbol  shift  is  in  effect, all characters
    entered  have  decimal    128  added  to    their codes before being
    inserted, also all  characters    between  128  and  159    have 128
    subtracted   from   their  codes.   This  means   that     graphic
    characters, greek symbols etc.    can then be  entered with single
    key  strokes,  and  have the benefit of keyboard auto-repeat for
    such  purposes    as  drawing  lines etc.  The mapping between the
    characters  can  easily  be  determined  by  inspecting the  256
    character set chart for your machine.    As  an    example, the 'M'
    character will draw a double horizontal  line, and 'c' will draw
    a greek 'pi' symbol.

    As an assistance to entering symbols, CONTROL F10 can be pressed
    to present a map of symbols, and to  allow one of the symbols to
    be selected using the mouse cursor, for insertion in the text at
    the text cursor position.



                      3-49             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide





    3.6.3 Deleting text

    Text is deleted in a number of ways.  Single characters and line
    breaks can be deleted either side of the cursor using the DELETE
    key  and the cursor pad DEL key.  Entire lines can  be    deleted,
    and  ranges  of  lines can be deleted  and  optionally    inserted
    elsewhere using the function keys.


    3.6.4 Moving text

    Text  can  be  moved  from  one part of the text to another,  in
    blocks of lines, using    the  CUT  and PASTE facilities.  Partial
    lines can be  deleted  by  inserting newlines at the appropriate
    places prior to CUTting. The CUT  lines  can  be  pasted  in the
    current item text, and are retained until another item is edited
    for when text has to be moved between items.

    The entire text  of another global or local item can be appended
    to the item text, and a named external file can be appended.


    3.6.5 Referencing

    Reference flags  can  be inserted in a number of ways.    The flag
    characters can be typed directly into the text    at  the required
    point (this may give strange and  confusing  results in the main
    display area whilst  in  progress - you are advised to watch the
    raw text area at the bottom of    the display whilst doing this).
    If a line  has    an  incomplete    reference in it, the editor will
    flash a '~' character  at  the    end of the line, to indicate the
    presence of an incomplete reference.

    Menus are provided to assist with the selection  of  the correct
    flags,    and  placement    of  the  flags    can be assisted.   Other
    parameteric information is requested for ends of references.

    Automatic referencing from the list of global or  local items is
    also  possible,  although parametric information then has to  be
    added manually if required.

    Complete references  can  be easily removed by moving the cursor
    to the reference and pressing CTRL F3.








                      3-50             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide





    3.6.6 Other functions

    Other functions provide help  on  flags and action codes, permit
    sequences of  editing  operations  to be mapped to function keys
    and  allow  the item edit to be exited retaining the  edits,  or
    quitted without retaining the changes.


    3.6.7 Control Keys

    The  following    control  keys  are  available  during  the  edit
    operation, and provide the various editing functions:-

    ESCAPE        EDIT  MENU - This option presents the edit menu,
            which  offers    the  options  available  on  the
            function keys as shown below.

    FUNCT KEY 1    HELP  -  This  presents  the editing help menu.
            This is described below.

    FUNCT KEY 2    REFRESH SCREEN -  This    key refreshes the screen
            display for when you  want  to    ensure    that the
            highlighting is properly done,    and  that a line
            just edited  is  displayed  to correctly reflect
            any references.

    FUNCT KEY 3    >> QUICK REFERENCE  -  This  presents  a menu of
            immediate references which can    be  applied to a
            single word of text.   This  menu  is  described
            below.

    FUNCT KEY 4    >> REFERENCE / INSERT   -     This presents  the
            REFERENCE  and INSERT menu  which  is  described
            below.

    FUNCT KEY 5    MARK START LINE FOR CUT - This notes the current
            line as the start line for a cut operation.

    FUNCT KEY 6    CUT LINES FROM MARKED - This cuts all lines from
            and including the marked one to the current one,
            placing  the  lines into a  paste  buffer.   Any
            previously cut lines will  be  lost.   The paste
            buffer    is  retained  until  overwritten with  a
            further  cut operation, and is available  within
            the edit of a subsequent item.    There is a limit
            to  the  number  of lines cut of  99  (around  4
            screensful).  The message "Too many  lines - not
            cut!"  is displayed if this is exceeded.



                      3-51             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



    FUNCT KEY 7    PASTE CUT LINES   -    This  inserts  the  lines
            contained in the paste buffer before the current
            line.  The  lines  are    still  available  in the
            paste buffer for insertion elsewhere.

    FUNCT KEY 8    TOGGLE SYMBOL SHIFT  -  This toggles the  symbol
            shift mode, turning it on if it is  off, and off
            if it is on.  The Symbol  shift mode is used for
            entering symbol characters.

    FUNCT KEY 9    QUIT - This abandons  the  changes  made  to the
            item and retains the item in the state it was in
            prior to the edit,  and  returns  to  the  frame
            display.

    FUNCT KEY 10    EXIT - This applies the changes made  during the
            edit to the item  being  edited,  and returns to
            the frame display.

    RETURN        SPLIT LINE   -  This has the effect of splitting
            the current line before the current  character.
            If the cursor is at the end of a line,    this has
            the effect of 'starting a new line'.

    CTRL PGUP    JOIN LINES - This joins the current line and the
            next line together.

    CTRL PGDN    DELETE LINE    - This deletes the whole current
            line.

    PGUP        PREVIOUS PAGE - This moves back one screenful of
            text within the edit  buffer.    If at the start,
            no action is taken.

    PGDN        NEXT PAGE - This moves to the  next screenful of
            text within the text  buffer.    If at the end of
            the text buffer, no action is taken.

    UP ARROW    PREVIOUS LINE  -  This    moves  the cursor to the
            previous line, retaining the  cursor position in
            the  line  if possible.  If at the start of  the
            text buffer, no action is taken.

    DOWN ARROW    NEXT LINE - This moves    the  cursor  to the next
            line, retaining the cursor position in    the line
            if possible.  If at the  end of the text buffer,
            no action is taken.

    RIGHT ARROW    NEXT CHARACTER    -  This  moves the cursor to the
            next  character,  moving  to  a  new   line   if



                      3-52             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



            necessary.  Note  that    the real contents of the
            line are used to  determine  the location of the
            next  character, and the position  in  the  main
            display  may  not change,  if  it  is  within  a
            reference or formatting operation.

    LEFT ARROW    PREVIOUS CHARACTER - This  moves  the  cursor to
            the previous  character,  moving to the previous
            line if necessary.  Note that the  real contents
            of  the line are used to determine the    location
            of the previous  character,  and the position in
            the main display may not change, if it is within
            a reference or formatting sequence.

    HOME        START OF LINE  -  This    moves  the cursor to the
            start of the current line.

    END        END OF LINE  -  This moves the cursor to the end
            of the current line.

    CTRL HOME    START OF WORD  -   This moves the cursor to  the
            start of the current word.

    CTRL END    END OF WORD - This moves  the  cursor to the end
            of the current word.

    CTRL RIGHT    DELETE TO END OF LINE   -     This  deletes  all
            characters  from  and  including   the     current
            character to the end of the current line.

    CTRL LEFT    DELETE TO START OF LINE    -  This  deletes  all
            characters before  the    current character on the
            current line.

    INS        TOGGLE  MODE  -  This    toggles   the  INSERT   /
            OVERWRITE  mode.    In    INSERT    mode,  all  (non
            control) characters typed are  inserted  at  the
            current cursor    position.   In    OVERWRITE  mode,
            characters  typed  overwrite characters  at  the
            current cursor position, unless the cursor is at
            the end of a line, in which  case the characters
            are inserted.

    DEL        DELETE  CURRENT CHARACTER -  This  deletes  the
            current character,  this  being  the one beneath
            which the cursor is displayed.    If at the end of
            a line, the next  line    is joined to the current
            line.





                      3-53             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



    DELETE        DELETE  PREVIOUS  CHARACTER  - This deletes the
            character just before the  current position.  If
            at the start of a line,  the line is joined with
            the previous one.

    CTRL B        BLANK LINE BEFORE -  This causes a blank line to
            be  inserted  BEFORE  the  current  line  in the
            text.

    CTRL A        BLANK LINE AFTER - This  causes  a blank line to
            be inserted AFTER the current line in the text.

    CTRL  Q     SPECIAL  CHARACTER - This permits the next key
            depression  to    be  inserted  verbatim into  the
            text.     Caution   should   be    exercised   when
            inserting   certain   control    characters,   as
            unpredictable results can occur.

    CTRL  E     EXPLAIN  ACTION  -  When  the  text cursor  is
            positioned  at    the  start  of an action string,
            depressing this key will cause an explanation of
            the action to be displayed.  Using this key when
            positioned  randomly  in  the  text  will  cause
            meaningless explanations to be displayed.

    Other keys have the effect of having the corresponding character
    inserted into the text at the current point.


    3.6.8 Quick references

    The quick  reference  menu  provides  for  the rapid addition of
    references which can be  applied  to a single word in the text.
    It also provides for references to be added  automatically  from
    either the global list of items or the local list of items.  The
    quick  reference options are available directly using the  SHIFT
    key along with the function keys.  The options available are:-



    SHIFT FKEY 1    FRAME  REFERENCE  - This causes the current word
            in the text to    be  flagged  as  a  frame  cross
            reference, with backtrack.

    SHIFT FKEY 2    STEP FRAME REF - This causes the current word in
            the   text  to    be  flagged  as  a  frame   step
            reference, with no backtrack.

    SHIFT FKEY 3    GLOBAL NOTE REF - This causes the  current  word
            in the text  to  be  flagged  as  a  global note



                      3-54             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



            reference.

    SHIFT FKEY 4    LOCAL NOTE REF - This causes the current word in
            the   text  to    be  flagged  as  a  local   note
            reference.

    SHIFT FKEY 5    GLOBAL MENU REF  -  This causes the current word
            in  the  text  to be flagged as  a  global  menu
            reference.

    SHIFT FKEY 6    LOCAL MENU REF - This causes the current word in
            the   text  to    be  flagged  as  a  local   menu
            reference.

    SHIFT FKEY 7    GLOBAL SCRIPT REF - This causes the current word
            in the    text  to  be  flagged as a global script
            reference.

    SHIFT FKEY 8    LOCAL SCRIPT REF - This causes the current word
            in the text to    be  flagged  as  a  local script
            reference.

    SHIFT FKEY 9    GLOBAL AUTOREFERENCE -    This  uses  the  list of
            global    items  to  flag  any occurrence of those
            items in the current item text.

    SHIFT FKEY 10    LOCAL  AUTOREFERENCE    -  This uses the list of
            local  items  to flag any  occurrence  of  those
            items in the current item text.


    3.6.9 Reference and insert Menu

    The reference and insert menu presents a number of types of item
    for insertion, and controls the setting up of  references.   The
    options are  also  available  directly    using  the CTRL key as a
    shift  with  the  function  keys.   The  menu  has the following
    options:-



    CTRL FKEY 1    ADD REFERENCE START - This presents a menu from
            which a reference type    can  be selected.  After
            selection,  the reference flags are inserted  at
            the start of the word within which the cursor is
            pointing.    The   rest  of  the  line    will  be
            highlighted, and the  reference  has  to have an
            end flagged using  the END OF REFERENCE function
            (see below).




                      3-55             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



    CTRL FKEY 2    END OF REFERENCE - This issues a request for the
            Parameter  value,  whereupon  a  suitable action
            string should be input, or the ESCAPE key should
            be  pressed  if  no  parameter    is  required.  A
            request   is   then  issued  for  the  Map  key,
            whereupon  if a key  mapping  is  required,  the
            single key to map  to  the  reference  should be
            entered,  followed  by RETURN. If no mapping  is
            required,  the ESCAPE key  should  be  pressed.
            After this, the reference  end    details  will be
            inserted  at the end of the current word.   This
            word can be the one to    which the reference flag
            was added, or a subsequent one.

    CTRL FKEY 3    REMOVE REFERENCE FLAGS     -   This removes  the
            reference  flags for the reference within  which
            the  cursor  is  placed.   If the cursor is  not
            within a reference the action is ignored.

    CTRL FKEY 4    INSERT FULL REFERENCE    -  This  option permits
            entry of a complete reference string,  prompting
            for each part as it is built up, and inserts the
            resulting   string   at   the    current   cursor
            position.  When the action part is  requested, a
            '?'  may  be   entered,  which    will  cause  the
            interactive action  builder to create the action
            specification.

    CTRL FKEY 5    INSERT ACTION -  This option presents a dialogue
            which    interactively    builds    up   an   action
            specification, presenting menus and  prompts  as
            it  goes, then inserts it at the current  cursor
            position.  A  full  action  specification is the
            result    (apart    from   the  optional  formatting
            pattern,  which  may  be  added  manually  after
            creation if required).

    CTRL FKEY 6    INSERT GLOBAL ITEM - This option allows the text
            from a global item to be  inserted at the end of
            the  current item.  It requests the name of  the
            item and then appends it to the text buffer.

    CTRL FKEY 7    INSERT LOCAL ITEM - This option allows the  text
            from  a local item to be inserted at the end  of
            the current item.  It  requests  the name of the
            item and then appends it to the text buffer.

    CTRL FKEY 8    INSERT FILE - This option allows the contents of
            a named  file  to  be inserted at the end of the
            current item.  It requests  the name of the file



                      3-56             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



            and then appends it to the text buffer.

    CTRL FKEY 9    DEFINE    MACRO  KEY  - This function is described
            below.

    CTRL FKEY 10    GRAPHIC  MAP  - This presents a popup display of
            the graphic  symbols,  from  which one character
            can be selected for insertion by positioning the
            mouse cursor and depressing  RETURN. The display
            can be cancelled with ESCAPE if no character  is
            to be selected.


    3.6.10 Help

    The help function presents  the  editing  help menu, which gives
    help text on the following topics:-

      -  GENERAL KEYS - Keys applicable to editing and viewing

      -  EDITING KEYS - Keys only applicable to editing

      -  FUNCTION KEYS - Function key mappings

      -  SHIFT FKEYS - Mappings for shifted function keys

      -  CTRL FKEYS - Mappings for function keys shifted with CTRL

      -  REFERENCE LETTERS - Flag letters for references

      -  CONTROL ACTIONS - Tokens for HyperShell control

      -  DOS/FILE ACTIONS - Tokens for program and file control

      -  SYSTEM VARIABLES - Variable names for system variables

      -  ACTION MODIFIERS - modifier flags

      -  DYNAMIC MENUS - Types of dynamic menu

      -  COLOUR SCHEMES - Colour scheme codes

      -  OPTION CODES - Option flag codes

      -  FUNCTION CODES - String function codes

      -  LENGTHS / LIMITS - Limits for HyperShell strings etc.

      -  SYMBOL KEYMAP - Mapping of characters to symbols




                      3-57             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



      -  GRAPHIC MAP - Map showing graphic symbols

      -  CHECK LETTERS - flags for HyperShell Check utility


    3.6.11 Key macros

    The define macro function, CTRL FKEY 9, issues the message:-

    Press Alt-X sequence Alt-X

    and awaits the depression of a mappable  Alt  shift / letter key
    combination.  Those combinations that  may  be    mapped are Alt-A
    through Alt-Z. The macro definition is performed by pressing the
    key to be mapped, followed by the sequence of key strokes  which
    are to form the macro, followed by another depression of the key
    to be mapped.  After the key  has  been  mapped,  whenever it is
    depressed, it 'plays back' the sequence of key strokes.  All key
    strokes are recordable, apart from menu selections, which cannot
    be  replayed.    During recording, the key depressions are  acted
    upon, so the cursor should be positioned where the sequence will
    be applicable.

    This  is  useful for  storing  common  key  sequences  for  easy
    replay.  Thus a macro to set the current  word    up  as    a  frame
    reference would be mapped to Alt-W as follows:-


         CTRL F9
         Alt-W
         CTRL HOME
         ~
         F
         CTRL END
         ~
         E
         Alt-W

    Thereafter,  to set any word up as a frame reference, the cursor
    is simply moved within    the  word  and Alt-W pressed.  Note that
    this function is only an example, and the  function described is
    mapped to the SHIFT Fkey 1 combination normally.

    The macro, once set up,  remains  in  effect  until  the  key is
    remapped, or the program is finally exited.  This not only means
    that the macro    can  be  used when editing other items, but also
    means  that  a key mapped to a frame name, for instance, can  be
    used in response to prompts issued from non-editing parts of the
    program.




                      3-58             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide







    3.7 View mode


    View mode is entered whenever an item is selected for viewing.

    The view mode display is like the edit    mode display, only it is
    restricted to operations which cannot affect the contents of the
    item  viewed.    The  interaction is otherwise very similar,  and
    does  not  need  explaining  separately.   Function  key  9  and
    Function key 10 can be used to exit from view mode.




    3.8 Selecting items


    The main menu offers a    number of options which result in 'paged
    displays'.  These  are    the  contents  list and the search list,
    which offer selection for frame navigation, and  the  global and
    local item lists, which offer item list editing and selection of
    items for editing.

    The various paged displays all have a similar appearance, with a
    heading showing the page number and  type  of  display,  and the
    items presented one to a line, apart from the search list, which
    offers one item every two lines,  preceded  by    the located line
    containing the search string.

    The left column shows the key mapped to the item for selection.
    This is followed by a blank area in which a '*'  appears  if the
    item  has  been  edited,  or a '@' appears if the item has  been
    moved.    This is followed by the item reference, which names  the
    item,  and  provides  an area selectable by the mouse.    This  is
    followed by an area containing the  frame  title,  or  the  item
    type, or the check options.  This is followed by a blank area in
    which  embedded  errors from the HyperShell checker program  are
    flagged.


    3.8.1 Control keys

    The following control keys are    available  during  the item list
    display, and provide the various item list editing functions:-





                      3-59             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



    RETURN        SELECT -  This    option is only available for the
            frame  list  displays,    and has  the  effect  of
            selecting  the frame referenced.  If the  cursor
            is  not  over  a  reference,  the  next page  is
            displayed.

    RETURN         ITEM  EDIT MENU - This option is only available
            for  the  item     list    displays,  and    is  only
            activated if the  mouse cursor is currently over
            an item.  It presents  the item edit menu, which
            offers the options described for  the  item edit
            menu below.

    ESCAPE         EXIT PAGED DISPLAY - This key cancels the paged
            display, returning to the frame  display for the
            last frame referenced.

    KEY '/'     SEARCH - This key  is  only  available    for  the
            global    item  list  display,  and  causes a text
            search mode to be entered, to enable a search to
            be made of all global items for a given string.
            The  search is    made  against  all  item  names,
            titles    and  item  texts.  This  is  useful  for
            finding  all  items that reference a  particular
            item, or for finding an item by name.

    FUNCT KEY 3    SEARCH - as for above.

    FUNCT KEY 1    HELP  - This key causes the help display for the
            paged display mode to be presented.


    3.8.2 Item Edit Menu

    The item edit menu permits editing of the item list, and of  the
    items.    It offers the following options:-

      -  EDIT ITEM - Presents item for editing

      -  VIEW ITEM - Presents item for viewing

      -  CHANGE DETAILS - Allows item name etc.  to be modified

      -  INSERT NEW AFTER - Permits new item to be added

      -  MARK ITEM - Marks item for later reference

      -  INSERT MARKED ITEM AFTER - Moves marked item to after this





                      3-60             Version 2.5








    HyperShell        HyperShell Editor     Reference Guide



      -  DELETE ITEM - Confirms, then deletes item

    The edit item option enters edit  mode    on  the  item  selected,
    permitting the text of the item to be edited.

    The  view  item option enters view mode on  the  item  selected,
    permitting the text of the item to be displayed.

    The change details option allows the name  and title of the item
    (or equivalent details) to be modified.

    The insert after  option  permits  a  new item to be created and
    inserted after    the  selected  item.   An  existing  item can be
    duplicated by first marking it, and  then  requesting a new item
    creation, or by specifying the name  of  the  existing item when
    prompted.

    The mark item option  simply  remembers the selected item, ready
    for further operations involving that item.

    The  move  marked item option moves a previously marked item  to
    after  the  selected  item.  The marked item need not be on  the
    currently displayed page, and can be moved forward  or    backward
    in the file.

    The  delete  item  option  deletes  the  selected  item,   after
    confirming that the deletion is required.  The first page of the
    item list is  always  displayed  after a deletion, regardless of
    which page was on display when the delete was requested.

    In order to create the first 'local' item after a frame, an item
    creation should be specified  from the global item display after
    the  desired  frame.   This  will create the first local  item.
    Selecting the local item list from the frame  display  will then
    permit the item to be  edited,    or  further  local  items  to be
    created.  Alternatively, local items  can  be  inserted from the
    frame display using the control menu or shifted function keys.
















                      3-61             Version 2.5








    HyperShell           HyperShell Checker     Reference Guide









                    Chapter 4

                   HyperShell Checker




    4.1 Introduction


    The HyperShell Checker program is a  utility  designed    to  do a
    certain degree of integrity checking on the Hyperfile.

    It performs  a number of checks on cross references, duplicates,
    action    codes  in action references, scripts and menus,  dynamic
    menu   codes,  formatting  codes,  sizing  checks  and     section
    ordering.

    It can provide summary totals showing the number  of  frames and
    other reference items, as well as diagnostic counts.

    It can produce a cross-reference file for reference when editing
    the hyperfile.

    It  can  automatically    generate frames and items which  do  not
    exist, and for which there is a reference.

    It  can embed error  messages  for  use  within  the  HyperShell
    editor.




    4.2 Invocation


    The HyperShell Checker is  invoked  with  the  following command
    line.



         HC {options} hyperfile

    The hyperfile specification is the name  of  the hyperfile to be



                      4-62             Version 2.5








    HyperShell           HyperShell Checker     Reference Guide



    checked.  It has a default extension  of  .HYP. The command line
    options control the program execution as follows:-



         -a      check actions for menus with action strings
         -b      flag references in text to frames and global items
         -c      create unresolved referenced items
         -e      create listing with embedded errors (sets -l, -n)
         -f      check frame references for menus without actions
         -g      full generation processing - options -e -c -u
         -l      list file during second phase
         -n      suppress line numbers in listing
         -p      suppress frame length check (for paged frames)
         -r      produce reference counts for items
         -s      suppress summary totals
         -t      suppress audit trail
         -u      suppress errors for unresolved references
         -x      suppress menu length check
         -z      produce cross reference file




    4.3 Operation


    The program performs four phases of processing.

    The first phase reads through the hyperfile,  creating    an index
    of frames, menus, notes and scripts.  Items with duplicate names
    (apart from items local to frames) are reported  as  errors.  If
    no frame references are found the program aborts.

    The second phase reads through the file  again, and is the stage
    at  which the most  processing    is  performed.     References  are
    checked, actions are checked, sizes are  checked.   A listing is
    optionally produced on standard  output,  containing  the errors
    embedded  within   it.     Unresolved  references  are  optionally
    created.  Line    numbers  are  added to each line output, and can
    optionally be suppressed.  References to frames and global items
    can optionally have flags added - this takes quite a  while  for
    large  hyperfiles,  so should  be  used  infrequently  -  it  is
    advisable to check  the  results  of  this action afterwards, as
    some unexpected flagging may  have  occurred.    The  matching of
    these  references  is  done  on  a selective basis, and not  all
    expected  occurrences  will be flagged.  If the cross  reference
    file has been requested, this is created during this pass.





                      4-63             Version 2.5








    HyperShell           HyperShell Checker     Reference Guide



    The third phase scans the index for items  that  have  not  been
    referenced directly, producing a warning message for these.  The
    items may have been referenced indirectly, so  the  warnings are
    only a rough guide.  Reference counts are optionally printed out
    at this stage.

    The  fourth  phase  prints the summary counts on standard  error
    output.

    An audit trail is produced throughout the run  to show progress,
    and the  location of errors.  This is produced on standard error
    output.

    The standard output can  be  redirected to a file.  This is used
    with the options  which  generate listings such as -e or -g, and
    the  -b option.  For example, to generate a processed  hyperfile
    with  added  unreferenced  items  and  flagged    references,  the
    following command line could be used:-

    hc -g -b draft1 > draft2.hyp

    As standard error output  is not redirected, the audit trail and
    summary are printed to the screen.




    4.4 Check switches


    Some of the settings can be controlled via the .CHECK section in
    the hyperfile.    This takes the form:-



         .CHECK {-options}{+options}

    The options following '-'  are    disabled,  the options following
    '+'  are  enabled.   The   following   option    letters  can  be
    specified:-


         a         check actions for menus with action strings
         f         check frame references for menus without actions
         p         suppress frame length check (for paged frames)
         u         suppress errors for unresolved references
         x         suppress menu length check

    The check section can appear a number of times in the hyperfile,
    and can be used to suppress unwanted checking within menus etc.



                      4-64             Version 2.5








    HyperShell           HyperShell Checker     Reference Guide



    An example sets options 'a' and 'u' and disables options 'f' and
    'p':-

    .CHECK -f+au-p

    Note that the + and - flags can  appear  more  than once, and in
    any order, and can be followed by a number of options.




    4.5 Cross reference file


    The cross reference file is produced by specifying the -z switch
    on the command line.  This causes a file  to be created with the
    same name as the hyperfile, but with an extension of .XRF.  This
    file contains two columns  of  information.   The  first  column
    shows the type and name of the reference  made by the item whose
    type and name  appear in the second column.  The sequence of the
    file  is  the  same  as  the  sequence    of  occurrences  of  the
    references  in    the  hyperfile,  and  will  be    grouped  by  the
    referencing item.  To group the file by the  referenced item, to
    show which items reference  each  item,  the  file can be sorted
    using the MSDOS SORT filter.  This is done as follows:-

    SORT < DEMO.XRF > DEMO.XRR

    This will produce a file  called  DEMO.XRR  containing the cross
    references sorted and grouped by referenced item.

    The cross  reference  files  can  be  printed  out and used as a
    reference when editing the hyperfile.




    4.6 Using the Checker


    The   various    options  are  valuable    at  various  stages   of
    preparation of the hyperfile,  and  familiarity  with these will
    prove beneficial.

    It is useful to run the checker after every major edit, in order
    that unreferenced items and non-existant referenced items can be
    determined.

    The  reference counts are  a  measure  of  the    balance  of  the
    hyperfile, particularly when considered together, and  can  give



                      4-65             Version 2.5








    HyperShell           HyperShell Printer     Reference Guide



    some indication of the usability of the material.




















































                      5-66             Version 2.5








    HyperShell           HyperShell Printer     Reference Guide









                    Chapter 5

                   HyperShell Printer




    5.1 Introduction


    The HyperShell Printer program provides a means  of  producing a
    formatted listing of a hyperfile.  In its simplest form, this is
    just  a  list  of  the frames in the hyperfile,  with  an  index
    printed at the end.  Additional  items    and  information  can be
    listed by use of control flags.  These are as follows:-





         -p   Send output straight to printer
         -e   As for 'p', but highlight using Epson compatible codes
         -s   Do 'soft' form feeds between pages
         -n   Don't do page breaks or index
         -d   Produce heading giving file name, rather than 1st title
         -r   List references after item
         -f   Produce full list of all items

    The output goes, by  default, to the screen.  It can be directed
    to a printer  using  the  -p  or  -e  flags,  or to a file using
    command line redirection - e.g.

    hp test > test.lis

    The  full  list  flag  causes all items to be listed,  including
    menus, notes, scripts etc.

    The list reference flag is used to list  the  actions  mapped to
    each reference after HEADER, FOOTER, NOTE and FRAME items.

    If page breaks are suppressed, an index is not produced.






                      5-67             Version 2.5








    HyperShell         Quick Reference     Reference Guide









                   Appendix A

                 Quick Reference




    A.1 File format



    .REMARK
    (text)
    .CHECK settings

    .NOTE name
    (text with formatting and references)
    .MENU name
    (options)
    .SCRIPT name
    (actions)
    .SCRIPT SETUP
    (limited actions)
    .HEADER
    (text with formatting and references)
    .FOOTER
    (text with formatting and references)
    .INDEX

    .FRAME name
    .TITLE title text
    (text with formatting and references)
    .MENU name
    (options)
    .NOTE name
    (text with formatting and references)
    .SCRIPT name
    (actions)
    .END








                      5-68             Version 2.5








    HyperShell         Quick Reference     Reference Guide







    A.2 References


    Curly braces indicate optional parameters.


    ~Fframename{~Paction}{~Kx}~E
    ~fframename{~Paction}{~Kx}~E
    ~nlocalnote{~Paction}{~Kx}~E
    ~Nglobalnote{~Paction}{~Kx}~E
    ~tfilenote{~Paction}{~Kx}~E
    ~mlocalmenu{~Paction}{~Kx}~E
    ~Mglobalmenu{~Paction}{~Kx}~E
    ~slocalscript{~Paction}{~Kx}~E
    ~Sglobalscript{~Paction}{~Kx}~E
    ~Aname~Paction{~Kx}~E
    ~Ientry area~Paction pattern{~Kx}~E




    A.3 Formatting



    ~Ln     (nn = 1 to 23)                Line
    ~Cn     (nn = 1 to 80)                Column
    ~Wn     (nn = 1 to 72)                Field width
    ~G                           Screen break
    ~Tc     (c= K,B,G,C,R,M,Y,W,k,b,g,c,r,m,y,w)  Text color
    ~Bc     (c= K,B,G,C,R,M,Y,W)               Background color
    ~Vi     (i= L,N,H)     Low, Normal, High Video (for mono displays)
    ~Dstb     (s=A to Z;t,b as for ~T,~B)           Colour scheme
    ~On     (n=0,1,2 etc) - prints ON or OFF      Option setting
    ~H                           Hidden line
    ~Q                           Immediate reference




    A.4 Menu format



    In a menu, choices can have an action specification appended :-




                      5-69             Version 2.5








    HyperShell         Quick Reference     Reference Guide



    choice 1  |action
    choice 2  |action
    etc      |action




    A.5 Variables


    System variables - these cannot be set, but can be expanded.




    $0    full path name of current HyperShell program
    $1    current frame name
    $2    current frame title
    $3    current file name
    $4    current date
    $5    current time
    $6    backtrack list depth
    $7    current directory
    $8    original directory
    $9    HyperShell name and version
    $?    Error status of last error
    $@    Remaining memory
    $_    File prompt (becomes null string when viewing file)
    $^    Numeric exit code from command executed via X/x action.

    These can be set

    $:    Exclusion list of file extensions
    $<    Filename from directory display
    $>    File extension from directory display

    Application  variables    -  these  are  set  by    an   application
    hyperfile, and can be expanded.



    $A to $Z      application variables
    $a to $z      application variables
    $(xxxxxx)     named application variable

    Variables are expanded in each line in text before it is displayed
    and in each action string before it is executed.






                      5-70             Version 2.5








    HyperShell         Quick Reference     Reference Guide







    A.6 Actions



    Axxxxx           do action xxxxx
    acxxxxx        do action xxxxx if condition c is set
    B           backtrack one frame
    bn           backtrack to depth n
    C           Change drive/directory
    D{command line}    Dos shell command
    d{command line}    Dos shell command (don't wait when finished)
    E           Execute command with no return (Chain)
    evsabc...       Expand (split) v on s to a,b,c etc.
    F{name{^file}}       Go to frame (first) {in file} (stack backtrack)
    f{name{^file}}       Go to frame (first) {in file} (replace backtrack)
    H           Add note to notepad
    h           Remove note from notepad
    I           Select next input field
    Jnn           Unconditional jump (in script)
    jxnn           Conditional jump (in script)
    Kkkaction       Map key kk to action
               kk = F1-F0,S1-S0,A1-A0,C1-C0,=x
    Lname           Label name - in script. No action otherwise.
    lvnamed        Load variable v into named variable 'named'
    Mname           Global menu
    mname           local menu
    Nname           Global note
    nname           local note
    Oos           Set run flag o(1=menusym,2=backtrack,3=savescr,
               4=autoref,7=tracing) to s(0=off,1=on)
               Set colour option o(A-Z - See below)
    ostring        Output to printer if enabled, else display
    Pstring        Pop message with string in it
    pstring        Display message with string in it (no wait)
    Q           Quit to DOS
    q           Quit script
    R           Read file (formatted)
    rfilename       Open file for reading (close if no param)
    Sname           Global script
    sname           local script
    Tfilename       Type file
    tfilename       Display file as popup note
    Vxvalue        Set variable x to value
    vxvalue        Test variable x
    Wstring        Write string to file
    wfilename       Open file for writing (close if no param)



                      5-71             Version 2.5








    HyperShell         Quick Reference     Reference Guide



    Xcomm args       Execute command with arguments
    xcomm args       Execute command with arguments (no wait)
    Y           Reset error status to zero
    yx           Refresh frame display (if param, display next page)




    A.7 Action modifiers



    In place of direct values (if second letter not modifier, tries third)
    on actions.

    ?prompt        Issue prompt, get string and pass back as
               parameter to action

    %envvar        Use value of environment variable as action parameter

    &funcspec       Use resulting string from function evaluation

    @menuspec       Use chosen value/action from menu display

    +           'Next' frame in current file

    !{F/L/R}{key}       next line from input file / noted references

    =           integer arithmetic expression (involving variables)

    Action modifier can be followed by '|pattern' where pattern contains
    instances of '%s' to replace with result of modifier. e.g.

             xxxxxx %s yyyyy %s zzzzz %s hhhhhh

    A maximum of three '%s' is allowed in the pattern.




    A.8 Function codes



    The available function codes are as follows:-

    L  -  Length of arg
    A  -  ASCII value of first char of arg
    C  -  character with ASCII value arg
    Nn -  nth character in arg



                      5-72             Version 2.5








    HyperShell         Quick Reference     Reference Guide



    Sn -  substring starting at nth character of arg
    T  -  Title of frame with name arg
    Mk -  string mapped to key 'k'
    Uc -  substring of arg up to, but not including character 'c'
    Fc -  substring of arg from character 'c' inclusive
    Ic -  index of character 'c' in arg, or 0 if not found
    K  -  character typed in response to arg as popup message




    A.9 Dynamic menus



    These are available via the @ action modifier, and replace
    the 'menuspec'.

    B           Backtrack list as menu (returning level number)
    C           Current Hyperfile contents list as menu
    Dwildspec      Directory listing (extension stripped)
    dwildspec      Directory listing (with extension)
    Ewildspec      Directory listing (directories only)
    Ffilename      Contents of file as popup menu
    Lwildspec      Extended directory display
    lwildspec      Extended directory display with actions added
    M(or m)name    Global/local menu
    N(n or t)name  Global/local/file note
    R           Notepad paged display
    Sstring        Search for string in titles of current file
    sstring        Search for string in titles of open files
    Xstring        Search for string in titles and texts of current file
    xstring        Search for string in titles and texts of open files




    A.10 Option codes




    Showing option code, command line flag, and default setting.

          0 -n    Notepad file creation (off)
          1 -f    Symbols on menus (on)
          2 -b    Backtrack recording (on)
          3 -x    Notepad reference extension (on)
          4 -a    Auto reference (off)
          5 -p    Enable printer (off)



                      5-73             Version 2.5








    HyperShell         Quick Reference     Reference Guide



          6 -r    Display remaining space on exit (off)
          7 -t    Script label tracing (off)
          8 -w    Give warning of unavailable references (on)
          9 -l(-k)    Stop highlight in 'T' list (strip 8th bit for
                for WordStar(tm) format files)



    A.11 Colours



    Option names for colour settings (with defaults) are:-

         A        wB        Action reference
         B        WK(bl)  (Blink)
         C        yB        Menu choice
         D        KW        Default title
         E        yK        Frame reference (replace)
         F        wK        Frame reference (stack)
         G        KK        (Ghost)
         H        KR        Menu heading
         I        yY        Input field
         J        KG        Note heading and border
         K        yG        Note
         L        RK        (Low intensity)
         M        KW        Menu reference
         N        gK        Note reference
         O        KY        Menu selection
         P        yR(bl)  Popup message
         Q        wR(bl)  (Quick)
         R        KW        Request / message
         S        yG        Script reference
         T        WK        Frame text
         U        YK        (User 1)
         V        MK        (User 2)
         W        GK        (User 3)
         X        RK        (User 4)
         Y        BK        (User 5)
         Z        rK        (User 6)




    A.12 Colour codes




         K        Black



                      5-74             Version 2.5








    HyperShell         Quick Reference     Reference Guide



         B        Blue
         G        Green
         C        Cyan
         R        Red
         M        Magenta
         Y        Yellow (brown)
         W        White (light grey)
         k        Dark grey         (Foreground only)
         b        Light blue         (Foreground only)
         g        Light green      (Foreground only)
         c        Light Cyan         (Foreground only)
         r        Light red         (Foreground only)
         m        Light magenta    (Foreground only)
         y        Light yellow     (Foreground only)
         w        Bright white     (Foreground only)






































                      5-75             Version 2.5








    HyperShell         Quick Reference     Reference Guide







    A.13 Error codes


    The following error codes are set  in variable '?'. The variable
    is only reset on command (by the 'Y' action).


         0        Success - (after status cleared)
         1        Operation cancelled
         2        No choice from menu
         3        End of file when reading
         4        Cannot open file
         5        File is not open
         6        File is already open
         7        File has changed
         8        At start of backtrack
         9        Divide by 0 in expression
         10     Value not expected in expression
         11     Value expected in expression
         12     Undefined opcode in expression
         13     Unmatched parenthesis in expression
         14     Syntax error in expression
         15     Script not available
         16     Menu not available
         17     Note not available
         18     Frame not available
         19     Key not defined
         20     Invalid key code
         21     Local reference - cannot be noted
         22     Not at reference when key pressed
         23     Key not mapped
         24     No action or action disabled
         25     Invalid action code
         26     No command present
         27     Environment variable not defined
         28     Invalid dynamic menu
         29     Line too wide for screen
         30     String too long
         31     Too many lines in frame
         32     Maximum script size reached
         33     Maximum menu size reached








                      5-76             Version 2.5








    HyperShell         Quick Reference     Reference Guide







    A.14 Jump conditions


    The following condition codes are used in the 'j' action.


         e        variable equals string (lexical or numeric)
         n        variable not equal to string
         g        variable greater than string (lexical or numeric)
         l        variable less than string (lexical or numeric)
         d        variable is defined
         u        variable is undefined
         c        variable contains string
         w        variable is contained within string
         s        jump if error status set
         o        jump if error status O.K.




    A.15 Reserved characters


    The  following    characters  cannot appear within the second  (or
    third if the second is not one of  them)  position  of an action
    specification, apart from for their stated purpose.


         @        Dynamic menu
         &        String function
         !        Read record
         +        Next framename
         =        Expression evaluation
         %        Environment variable
         ?        Prompted input

    The following characters cannot appear in  the body of an action
    specification, apart from for their stated purpose.


         $        Variable expansion token
         |        Action modifier pattern specification
         ^        (Within frame names) Hyperfile separator
         ;        Multiple action separator





                      5-77             Version 2.5








    HyperShell         Quick Reference     Reference Guide



    The following characters cannot appear within frame text,  apart
    from for their stated purpose.




         ~        Reference and formatting directive flag
         $        Variable expansion token
         .        (At beginning of line) Section flag

    - END OF DOCUMENT -










































                      5-78             Version 2.5








    HyperShell         Quick Reference     Reference Guide







               Table of Contents


    Chapter 1 Introduction                       2

       1.1 Introduction                       2

    Chapter 2 The Hyperfile                    3

       2.1 File contents                       3

          2.1.1 Remarks                       3
          2.1.2 Check                       3
          2.1.3 Header                       4
          2.1.4 Footer                       4
          2.1.5 Global Notes                   5
          2.1.6 Global Menus                   5
          2.1.7 Global Scripts                   5
          2.1.8 Setup Script                   6
          2.1.9 Index                       6
          2.1.10 Frames                       6

         2.1.10.1 Name                       7
         2.1.10.2 Title                    7
         2.1.10.3 Text                       7
         2.1.10.4 Notes                    8
         2.1.10.5 Menus                    8
         2.1.10.6 Scripts                   9
         2.1.10.7 End                       9

       2.2 Text annotation                       10

          2.2.1 References                       10

         2.2.1.1 Frame                       10
         2.2.1.2 Note                       11
         2.2.1.3 File note                   11
         2.2.1.4 Menu                       11
         2.2.1.5 Script                    11
         2.2.1.6 Action                    12
         2.2.1.7 Input field                   12
         2.2.1.8 Parameter section               13
         2.2.1.9 Key mapping                   13
         2.2.1.10 Immediate reference               13

          2.2.2 Formatting                       13



                      5-79             Version 2.5








    HyperShell         Quick Reference     Reference Guide




         2.2.2.1 Option display                14
         2.2.2.2 Line positioning               14
         2.2.2.3 Column positioning               14
         2.2.2.4 Width positioning               14
         2.2.2.5 Screen breaks                   15
         2.2.2.6 Hidden lines                   15
         2.2.2.7 Text/Background colours           15
         2.2.2.8 Display colour schemes            16
         2.2.2.9 Variables                   17

       2.3 Actions                           18

          2.3.1 Action tokens                   18

         2.3.1.1 A - Action                   18
         2.3.1.2 a - Conditional action            19
         2.3.1.3 B - Backtrack                   19
         2.3.1.4 b - Multiple backtrack            19
         2.3.1.5 C - Change drive / directory           20
         2.3.1.6 D/d - DOS command execution           20
         2.3.1.7 E - Command chaining               21
         2.3.1.8 e - expand variable               21
         2.3.1.9 F/f - Frame selection               21
         2.3.1.10 H/h - Notepad maintenance           22
         2.3.1.11 I - Select next input field           22
         2.3.1.12 J/j - Jump within script           23
         2.3.1.13 K - Set key mapping               24
         2.3.1.14 L - Label in script               24
         2.3.1.15 l - load named variable           25
         2.3.1.16 M/m - Popup menu display           25
         2.3.1.17 N/n - Popup note display           26
         2.3.1.18 O - Option setting               26
         2.3.1.19 o - Printer output               27
         2.3.1.20 P - Popup message               28
         2.3.1.21 p - Print message               28
         2.3.1.22 Q - Quit HyperShell               28
         2.3.1.23 q - Quit script               28
         2.3.1.24 R - Formatted read               28
         2.3.1.25 r - Open/close input file           29
         2.3.1.26 S/s - Execute script               29
         2.3.1.27 T - Type file                29
         2.3.1.28 t - file note                30
         2.3.1.29 V - Set variable               30
         2.3.1.30 v - Test variable               31
         2.3.1.31 W - Write record to file           31
         2.3.1.32 w - Open/close output file           31
         2.3.1.33 X/x - Execute program            32
         2.3.1.34 Y - Null action               32
         2.3.1.35 y - refresh frame display           32



                      2-80             Version 2.5








    HyperShell         Quick Reference     Reference Guide




          2.3.2 Action Modifiers                   32

         2.3.2.1 Prompts                   32
         2.3.2.2 Input file                   33
         2.3.2.3 Noted references               33
         2.3.2.4 Environment Variables               34
         2.3.2.5 Expression evaluation               34
         2.3.2.6 Functions                   34
         2.3.2.7 Dynamic menus                   36
         2.3.2.8 Pattern strings               37
         2.3.2.9 Multiple actions               37

       2.4 Dynamic menus                       37

          2.4.1 Paged displays                   38
          2.4.2 Simple menus                   38
          2.4.3 Other types                    39

       2.5 Variables                       39

          2.5.1 Variable assignment                39
          2.5.2 Variable substitution               40

       2.6 Alternative hypertext                   40
       2.7 Limits                           41

          2.7.1 sizes                       41
          2.7.2 numbers                       41

    Chapter 3 HyperShell Editor                   42

       3.1 Introduction                       42
       3.2 Invocation                       42
       3.3 Editor processing                   43
       3.4 Editor interaction                   44
       3.5 Frame Navigation                    44

          3.5.1 Control keys                   45
          3.5.2 Control menu                   47
          3.5.3 Help menu                       47

       3.6 Text editing                       48

          3.6.1 Moving around                   49
          3.6.2 Inserting text                   49
          3.6.3 Deleting text                   50
          3.6.4 Moving text                    50
          3.6.5 Referencing                    50
          3.6.6 Other functions                   51



                      2-81             Version 2.5








    HyperShell         Quick Reference     Reference Guide



          3.6.7 Control Keys                   51
          3.6.8 Quick references                   54
          3.6.9 Reference and insert Menu               55
          3.6.10 Help                       57
          3.6.11 Key macros                    58

       3.7 View mode                       59
       3.8 Selecting items                       59

          3.8.1 Control keys                   59
          3.8.2 Item Edit Menu                   60

    Chapter 4 HyperShell Checker                   62

       4.1 Introduction                       62
       4.2 Invocation                       62
       4.3 Operation                       63
       4.4 Check switches                       64
       4.5 Cross reference file                   65
       4.6 Using the Checker                   65

    Chapter 5 HyperShell Printer                   67

       5.1 Introduction                       67

    Appendix A Quick Reference                   68

       A.1 File format                       68
       A.2 References                       69
       A.3 Formatting                       69
       A.4 Menu format                       69
       A.5 Variables                       70
       A.6 Actions                           71
       A.7 Action modifiers                    72
       A.8 Function codes                       72
       A.9 Dynamic menus                       73
       A.10 Option codes                       73
       A.11 Colours                        74
       A.12 Colour codes                       74
       A.13 Error codes                       76
       A.14 Jump conditions                    77
       A.15 Reserved characters                   77











                      3-82             Version 2.5