

       +------------------------------------------------------+      
       |TUTORIAL FOR SYSTEM MANAGERS: SETTING UP HYBROW MENUS |
       +------------------------------------------------------+

Select this if you are uncertain about HYBROW navigation:
[tutorial1:How_to_navigate_hybrow_menus]


You are now looking at the opening menu of HYBROW, always stored in the
default start directory as a file called "start".

Each screen HYBROW displays, is actually derived from an ASCII plain text
file which contains HYBROW links.  This screen, for instance, comes from
    \~PWD~/start

Examples of HYBROW links
1. File-Display Link    This displays the sample file "sample" found in the 
   [sample]             specified directory path upon invoking hybrow, (eg.
                        hybrow -smy_directory) or the default directory path
                        fixed during compilation. Other uses: [sample01:]


2. Execute-only Link    This links to a command/unix shell script/executable
   [!ls -al]            and executes it.  If there is an output, it will be
                        transiently displayed.

                        To hide the command, place a colon at the end and
                        follow it with whatever characters you wish to be
                        displayed, if any.  Example:
                        \[!ls -al:list current directory\] will display only
                        \[list current directory\].


3. Execute-Display Link This also links to commands as in the Execute-only
   [@ls -al]            type of link, with a difference: the output is not
                        transient, but is displayed as a HYBROW menu/display.
                        So to exit from the new display, you just press the
                        LEFT arrow key.

                        Other examples:
                        \[@cat file1 file2\:display file1 followed by file2\]
                        \[@cat start:display this menu, the start menu\]



Handling variables
------------------

HYBROW can handle variables within the links (ie. within square brackets)
by looking for the dollar symbol  eg. $variable, $VAR etc.

You can set the variable by placing a line in the file ".hybrowrc" (in the
default directory for the system manager, or in the place where you
compiled HYBROW for the individual user, or in the directory where you
invoked hybrow, or in any directory specified with the -s option).

Example:

\[@echo $EDITOR\]   a command to display the value of your EDITOR variable

For more examples, select: [sample01:]


You can alter these variables or set entirely new ones in HYBROW by means
of field-filling links as described below. 


4. Field-Filling Link   The link here looks like a blank highlighted zone
                        flanked by a pair of "|".  The actual link that
                        generated this blank is :
[$variableA=]  \[$variableA=\]
[$variableB=default]  You can enter a default value like this:
                            \[$variableB=default\]
                      in which case the word "default" appears in the blank.
                      This link when combined with Execute-only or Execute-
                      display links below, provides a very useful combination.
[$variableC=!echo $variableC]  is generated by \[$variableC=!echo $variableC\]
[$variableD=@echo $variableD]  is generated by \[$variableD=@echo $variableD\]
                      Within the filling mode, left and right arrow keys now
                      control movement within the field. Backspace keys will
                      enable delete and so on. Pressing return will finish the
                      filling, execute the command with the variable value 
                      you have entered and take you out of field filling mode.
   Control-B Feature  When you are within the filling mode, pressing
                      Control-B simultaneously will invoke a display of your
                      current working directory.  This feature was added to
                      facilitate filling in input files when biocomputing 
                      programs are involved in the interface. Navigate to the
                      appropriate file and press the left arrow in order to 
                      enter the filename into the field.

5. Directory-Browser  The directory browser link provides the user with a link
    Link                to a display of the contents of the current working 
                        directory.  At its simplest, it looks like \[!BROWSE\]
[!BROWSE]             This display is not just a display. It allows the user
                        to traverse the directory hierarchy merely by selecting
                        the appropriate directory name. 
                      The highlighted file can be displayed, executed, deleted,
                        copied, edited, renamed, etc. These actions are invoked
                        by pressing the appropriate key as stated in the header
                        of the display.
                      More actions can be included, merely by restating the
                        link.  For example,
                      [!BROWSE -ocat\\ $HYBROW/sample <sampleheader]
                        will provide the additional option "o"(case sensitive)
                        which will invoke the unix command line command:

                              %   cat $HYBROW/sample

                        where $HYBROW is defined in the file .hybrowrc
              (Note: the space between cat and $HYBROW/sample is made
               significant by two backslashes "\\\\ ".  So for every space
               in your command, precede it with two backslashes.)

5. Directory Browser Link cont'd

                      [!BROWSE -ocat\\ $HYBROW/sample <sampleheader]
                      The symbol "<sampleheader" above will cause the contents
                        of the file "sampleheader" to be piped into the
                        beginning of the directory-browser display.
                      This header is best used to describe additional commands
                        that you have implemented. Take a look at the 
                        [sampleheader] file.

                      Suppose instead of acting on a pre-stated file eg.
                      $HYBROW/sample, and you wish to make a command operate
                      on the highlighted file as input, then the variable
                      $XIFILE can be used in this context to substitute for
                      the highlighted file.

                      [!BROWSE -xtail\\ \$XIFILE <sampleheader]

                      will list the tail of the file against which the
                      cursor is placed.  (NOTE: the necessity of putting
                      in the backslashes before the space, and before the
                      "$XIFILE" to make the spaces literal.)

                      Using this browser, one can incorporate any command
                      to act on a given file and create a directory display
                      menu for the interfacing of a set of biocomputing
                      programs which act on files as input.

6. Gopher links     
    		      This implementation of HYBROW allows for links
		      to be made with Gopher holes.  However, only
		      three gopher file types are accessible: type 0,1 and 7.
		      Gopher links may be initiated using an execute-display
 		      link  [@$ngopher] where $ngopher is set in .hybrowrc
		      to the executable in the HYBROW home directory.
		      This program recursively generates such gopher links
		      and allows the traversal of a gopher directory hierarchy
    		      in the same way as the HYBROW links.
		      The default gopher site is specified in def.h.



MULTIPLE MENU HIERARCHIES
-------------------------

Set up a start file which branches to different hierarchies.
Each hierarchy can possess links that call files from other
hierarchies. For example, all hierarchies can use the same
set of help files because the execute-display command can
essentially "cat" any file. eg [@cat $other_hierarchy/file]

COMPOSITE MENU DISPLAY
----------------------

Simply compose the menu by listing out two or more different files
eg.  [@cat header body1 trailer]
The headers and trailers can be reused for other displays eg.
[@cat header body2 trailer].

DYNAMIC MENU FORMATION
----------------------

Suppose you wish to make an index of selectable links.
Compose a shell script to grep all files in a particular
directory or in a particular set of files for link identifiers 
ie. the square brackets.

Eg. the shell script file:   indexer

#!/bin/sh
echo "INDEX of LINKS"
cat start sample sample01 tutorial tutorial1 | grep "\[.*\]" | sort | uniq

and call indexer like this  [@$HYBROW/indexer]

Of course, the "indexer" shell script can include more code to spruce up the 
output and so on.

IMPORTANT:
Don't forget to change mode of the shell script "indexer" to an executable
%  chmod +x indexer

DYNAMIC LINK FORMATION
----------------------

Suppose you wish to generate file-display links at every mention of a
set of words in a text file.  An example will be the generation of
links with glossary words, say to files bearing the name of the word itself,
containing a brief definition.

So instead of [@cat sampletext], invoke a filter shell script, say "xgloss"
[@xgloss sampletext], whose contents are as follows (it works for Ultrix
version 4.2):

#!/bin/sh
cat $1 > /tmp/xglossdisp$$
cd $HYBROW/glossary
for i in *
do
cat /tmp/xglossdisp$$ | sed "s/\($i\)/\[@cat \$HYBROW\/glossary\/\1:\1\]/" \
 > /tmp/xgtemp$$
mv /tmp/xgtemp$$ /tmp/xglossdisp$$
done
cat /tmp/xglossdisp$$
rm -f /tmp/xglossdisp$$

Thus, using less than a dozen lines of shell script code, one can dynamically
and automatically form links.

The other alternative is to have a sample dictionary of keywords and 
their associated links in a file, say, sampledict

keyword1 \[@cat $HYBROW/glossary/word1:keyword1\]
keyword2 \[@cat $HYBROW/glossary/word2:keyword2\]
keyword3 \[@cat $HYBROW/glossary/word3:keyword3\]
keyword4 \[@date:keyword4\]
keyword5 \[!man sed:keyword5\]
etc ...



The shell script, say xdict, will take a sample text and pick out
occurrences of the keywords in each line and substitute it with the
link associated with the keyword in the file sampledict.
This may be invoked from HYBROW by [@xdict sampledict sampletext]




The script, xdict, again less than a dozen lines, may look like for
Ultrix version 4.2.  The decent alternative is to get somebody to write
a C program or whatever that will do the same job more elegantly.

#!/bin/sh
cat $2 > /tmp/xdictdisp$$
for i in `cat $1 | awk -F\  '{ print $1 }'`
do
cat $1 | grep "^$i\ "  | sed "s/^.*\[/\[/" | sed 's/\//\\\//g' > /tmp/xdictlink$$
link=`cat /tmp/xdictlink$$`
cat /tmp/xdictdisp$$ | sed "s/$i/$link/" > /tmp/xdict$$
mv /tmp/xdict$$ /tmp/xdictdisp$$
done
cat /tmp/xdictdisp$$
rm -f /tmp/xdictdisp$$ /tmp/xdictlink$$







VARIABLES in HYBROW
-------------------
1. Predefined variables

Please note that all variables used by HYBROW are kept in the file .hybrowrc
of the default directory. Variable names are CASE-SENSITIVE!

Should the user wish to specify an alternative list, she is advised to make
a copy of .hybrowrc into the desired directory and alter it accordingly.
To use the personal .hybrowrc, the user should invoke HYBROW with the -s
option eg % hybrow -smy_directory

2. Variables in HYBROW displays

Variables are displayed in HYBROW menus using the command \\~variable~
They can be silently set by using \\~variable=value~ and this will
not be displayed by HYBROW.

3. Variables in HYBROW links

Variables are substituted for within HYBROW links by prefixing the variable
name with a dollar "$" symbol. 

SUMMARY
-------

The following set of links may be used as a template for building your
own menu.  See the file [!cat menutemplate].

Variable display  Current working directory:  \~PWD~
File-Display      [sample]
Execute-only      [!ls -al:list current directory] 
Execute-display   [@ls -al:display current directory]
 w/multiple cmds  [@echo "This is a full directory listing";ls -al:]
 w/variable       [@$my_path/mycommand]
Field-filling     [$variableA=]
 with default     [$variableB=default!echo $variableB; read dummy]
 with execute     [$variableC=!echo $variableC]
 with exec/d'play [$variableD=@echo $variableD]  
Dir/Browser       [!BROWSE]
 with comment     [!BROWSE:directory browser]
 with new command [!BROWSE -ocat\\ $HYBROW/sample:]
 with header      [!BROWSE -ocat\\ $HYBROW/sample <sampleheader:]
 with inputfile   [!BROWSE -xtail\\ \$XIFILE <sampleheader:]
 with multiple
   commands       [!BROWSE -ocat\\ sample -xtail\\ \$XIFILE <sampleheader:]
GOPHER links      [@$ngopher solomon.technet.sg 70]



Please send any comments/corrections/improvements/suggestions
about the above tutorial to:

Dr Tan Tin Wee
Department of Biochemistry
National University of Singapore
Kent Ridge
Singapore 0511
fax: (65)7791453
tel: (65)7723678
internet:  bchtantw@nuscc.nus.sg



