home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Black Box 4
/
BlackBox.cdr
/
editors
/
hypsh40c.arj
/
HYPDOC.LZH
/
CHAP7.TXT
< prev
next >
Wrap
Text File
|
1991-04-27
|
36KB
|
925 lines
HyperShell Users Guide Integrated Environment
HyperShell Integrated Development Environment
7. Integrated Environment
The Integrated Environment provides an environment for the interactive
creation and maintenance of hyperfiles. This program is consistent
with the main HyperShell reader program, providing the full reader
functionality as a subset.
The Integrated Environment is also designed to provide a base for a
new kind of application, where information can be readily added in the
form of frames, notes and the other HyperShell items.
It provides a number of functions additional to the reader component,
as follows:-
i. Editing of frames and other items.
ii. Item level and file level checking of syntax and cross
references.
iii. Frame and item text output direct to printer or to a file.
The additional functionality is fully configurable, as it is provided
in the form of:-
i. Additional actions to handle the editing operations.
ii. Additional functions and condition codes.
iii. Additional menus for selection of items, searches and check
scans.
iv. Additional menus for lists of local notes and other items.
v. A configurable editor, which can utilise the power of popup
menus, notes, functions and dynamic menus.
vi. A separate edit control `hyperfile' which may be used to provide
the editing environment.
The Integrated Environment has the following limitations compared with
the reader components.
i. It is limited to working on one hyperfile at a time. Attempts to
reference or pre-load other hyperfiles will be unsuccessful.
- 111 -
Integrated Environment HyperShell Users Guide
ii. It cannot read a compressed file which has been compressed with
the new `secret' flag. This is a deliberate restriction imposed to
protect hyperfiles produced by holders of HyperShell development
licences.
iii. It cannot handle certain hyperfiles which the HL.EXE component
can handle. This is due to storage requirements.
7.1 Edit methods
To reflect the varying requirements of different applications, a
number of different editing methods are available.
7.1.1 In memory edit
The default editing mode is `in memory', unless the file is estimated
to be too large to be comfortably edited in memory. This means that
the entire file is read into memory for editing, and is saved directly
to disk on exit.
Loading
Main file to memory
Control file to memory
Saving
1. Quit to original
or 2. Save whole file with or without backup
7.1.2 Edit from file
For files which are too large to be edited in memory, the `edit
against file' option is used. This can also be specified for those
files which can fit in memory, using the command line switch
-ef
This method holds the changes in memory until the save operation. It
then merges the changes with the original file. However, as this is a
rather disk intensive operation, another form of saving is also
offered. This is known as `incremental' saving, or `change file'
saving.
With this, rather than updating the main hyperfile, just the changes
are written to a file, along with a detailed index so that the order
of items reflects the editing session. This combined change and index
file is automatically read in on a subsequent run, and used to
reconstitute the appearance of the file when it was last saved.
Further changes can then be performed, and the results saved again.
- 112 -
HyperShell Users Guide Integrated Environment
This mode of operation keeps the memory requirements to a minimum, so
the change file can grow to a reasonable size before it is merged, if
indeed that is at all necessary. The merge operation, when it is
performed, takes the accumulated changes into account, merging the
changes in memory with those from the control file and the original
file.
The change file mode of operation has some useful side-effects. It is
possible, for instance, to work against a write protected hyperfile,
and thereby prevent any damage to the original file. It is simple to
rename the change file so that multiple change paths can exist. Thus
a number of `users' can hold their own changed view of the original
file. It is possible to save successive change files, such that a
change step can be `backed out' to the previous stage, without the
overhead of retaining full copies of the hyperfile at each stage.
Loading
- Main file from file
- Change file, if present, from file
- Control file to memory
Saving
1. Quit with no saving
a) and retain change file
b) and delete any change file
or 2. Merge Main with change file and memory
a) and continue
b) and exit
c) optional backup retention
or 3. Save change file
a) and continue
b) and exit
7.2 Edit control file
Edit functions can be built into a control file. Thus you could have
a self-contained menu driven incremental hyperfile which edits itself.
Edit functions can also be provided via a `hidden' control hyperfile,
called HS_IDE.HYP. This is loaded, if present, along with the
hyperfile named on the command line, and maps a key (usually the `#'
key), to bring an editing control menu into operation. This hyperfile
just contains global items, and is loaded at the end of the global
items for the main hyperfile, although it will not be visible in the
item lists.
The HS_IDE control file should not be present if you use built-in
editing control, although you can provide additional editing functions
from items in the main hyperfile.
- 113 -
Integrated Environment HyperShell Users Guide
7.3 File structure
If you intend using the integrated environment with existing
hyperfiles, you should note the following.
The integrated editing environment does not retain the order of the
single control items, such as the HEADER and FOOTER, but writes them
to the new file at the start.
Also all items, REMARKs, CHECKs, PRINTs etc. after a frame definition
are treated as local and belonging to that frame. All such items
before the first frame definition are treated as global. The `.END'
directive is therefore redundant, but you may wish to retain these in
existing hyperfiles for commentary purposes.
7.4 Keeping backups
Your hyperfiles are a valuable asset, as it takes you a lot of time
and creative effort to produce one. Because of this, you will not be
too happy to lose them. The best approach is to take copies of the
file on a regular basis.
If you use a hard disk, you should take copies on floppy disk
regularly, in case your hard disk suddenly decides not to work. You
can also make very frequent copies to a backup directory on the hard
disk, in case you accidentally delete something important.
The HyperShell integrated environment has been well tested, but there
is always the possibility with any software that unusual circumstances
may cause it to crash, losing the data being edited. The HyperShell
incremental save facilities allow you to take regular snapshots of
your editing in case this happens. It is up to you how frequently you
do these, but you have only yourself to blame if you lose everything
after a seven hour editing session. The nature of editing software is
such that the longer the session takes, the more chances are that the
unusual circumstance will occur.
The integrated environment monitors the available memory and gives
adequate warnings when it gets low. If you save your data immediately
the low memory warning is given, you will not run the risk of the
program running out completely. If you find the low memory limit (50k
by default) too high, you can configure it to be lower (or higher if
you think it too low!), but be warned that when memory runs out
altogether, the program halts with no chance of saving your changes.
7.5 Command line
The Integrated Environment command line is the same as for the HS/HL
component, but has the following additional flags:-
- 114 -
HyperShell Users Guide Integrated Environment
+---------------------------------------------------+
|-ef | Work against file, rather than in memory |
|-eb | Delete original, rather than saving as .BAK |
+---------------------------------------------------+
If you do not suppress the creation of a backup file, the original is
renamed to have a .BAK extension and the new file renamed to have the
original name. If the temporary file has a different pathname, as
specified in the TEMP environment variable, 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 new copy of the file as well as the backup
copy. 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.
New hyperfiles cannot be created by HI. An existing file is copied to
form the basis of the new hyperfile. The Hyperkit hyperfile allows
you to do this.
7.6 Program operation
As the integrated environment is a superset of the HyperShell reader,
it will function in the same fashion when you run it. If the memory
edit mode is in effect, the program will take longer to start, but
will run more quickly when displaying frames or using other items.
The contents list will show additional information to indicate where
each item is held, and to indicate if the item has failed a check
scan. This takes the form of additional indicators similar to the
matching frame flag set by searches.
The item location flags appear to the left of the item name, and have
the following values:-
blank Item is in original file
M Item is in memory
C Item is in the change file
R Item is read-only control item (not displayed)
The check fail indicator appears next to the item name, and is a `?'
character.
If edits have been performed on the file, attempting to use the normal
`Quit' action will cause a confirmation request to be issued, allowing
you to return to the program to save the changes.
- 115 -
Integrated Environment HyperShell Users Guide
The TEMP environment variable may be set to indicate the device and
directory path to be used for the temporary file used for regular
saves, and as a work file when the save and exit is used. It speeds
up the save and exit processing for when the `edit against file' mode
is used, if this is on a different drive to the original file.
Sufficient space must be available to accommodate the temporary file,
which will be at least as large as the edited file.
7.7 Editing operations
The editing facilities consist of file level, item level, and contents
level operations.
File level operations consist of the various save and exit with save
actions, as well as actions which treat external files as `items',
such as text file creation, editing, rename and deletion.
Item level operations handle the creation, renaming, checking,
relocation and deletion of frames and other items.
Contents level operations are handled by the edit mode, which provides
a full screen editor for editing the contents of frames, items and
text files.
A number of other supporting facilities are provided for searching and
selection of global and local items, scanning for errors, printing
frames or items, etc.
7.8 Edit mode
The edit mode provides a full screen editor, which is fully
configurable. The default mode of operation and key mappings are
described here.
The edits you make in edit mode do not have any effect until they are
saved. You can optionally QUIT out of edit mode if you do not wish to
save the edited item.
To save the item after editing it in edit mode, you press Function key
10. To quit without saving the changes, you press Function key 9 and
confirm that you want to quit. When you exit or quit from edit mode,
you are still in the integrated environment. Your changes will be in
memory, and you will have to do some form of file saving to make the
changes to the hyperfile permanently.
A blank line is added to the end of the edit buffer when edit mode is
entered. This is removed, if present, when the buffer is saved.
VIEW mode is a variation of edit mode, which works in the same way,
only does not permit the item to be saved, except to a disk file.
View mode is indicated on the bottom line, and by the bottom line
being a different colour to when in edit mode.
- 116 -
HyperShell Users Guide Integrated Environment
If you press Function key 9 in View mode, you will exit to the frame
display directly. If you accidentally press Function key 10, the edit
buffer will be saved to the buffer save file called EDITBUFF.SAV, and
you will remain in view mode.
7.8.1 Text display
The text is displayed in the top 22 lines of the screen, flush with
the left edge of the screen.
For Frames, Notes, the Header and the Footer, reference flags, tabs
and horizontal formatting controls are handled in the main display to
give the appearance the text will take when displayed. The current
line, being that over which the cursor is placed, is also displayed at
the bottom of the screen in its `raw' form, showing any reference and
formatting flags. For other items, the text will be shown in the main
display area in its raw form. All items can be toggled to the other
interpretation state at any time using Function key 4.
Variable tokens are not expanded, but are shown in their token form.
The screen will use the configured colours for frame and note items,
and will use the frame text colour configuration for other items. As
the text is edited, the edit mode will attempt to keep the colours for
new data correct. It is not always successful in doing this, and you
should not be alarmed by any incorrect colours. These can usually be
sorted out by refreshing the display (Function key 2), but may not be
corrected until the text is displayed as the item.
The bottom line of the display shows the type and name of the item
being edited, the current page and line number and the number of
pages. A `page' in this case is the screenfull of text displayed by
the editor, and most likely will not match the page number of a
multiple screen frame display. However, an indicator is shown
alongside the line number when the text cursor is on the estimated
`bottom' line of a frame.
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 the symbol
shift is in effect, and to indicate which margins are in effect.
7.9 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 attached to the system, the mouse cursor can be used to
position the text cursor, using the left mouse button. This may be
done in the main display area, or in the raw text display area if
precise positioning within references is required.
- 117 -
Integrated Environment HyperShell Users Guide
If the text is longer than 22 lines, the remaining text is available
by moving the cursor down, or by paging down using the PgDn key. A
menubar will be displayed at the right edge, which is used to indicate
the position of the text cursor in the buffer. If a mouse is
available, the mouse cursor can be clicked on the scrollbar to
position the text cursor at the approximate location in the buffer
represented on the scrollbar. The up and down arrows at top and
bottom of the scrollbar can be used to move up and down a screen at a
time, like the PgUp and PgDn keys.
7.9.1 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 current insertion mode is indicated by the cursor
shape, as in the string edit mode of the reader, a block signifying
insert mode and an underscore signifying overwrite mode.
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 boundary as specified by
option code O*7 (default 8).
Control characters, other than tabs, are not inserted, nor are decimal
codes above 175 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 as control
characters below decimal 32 can cause data to be lost.
Special symbols, with codes above decimal 175, 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 175 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 in the appendix. 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, the help menu (Function key 1)
may be configured to include a note display showing a map of symbols,
one of which may be selected positioning the mouse cursor and pressing
the HOME key. This inserts the character in the text at the text
cursor position.
7.9.2 Margins and formatting
Text auto-wraps at column 80, unless a right margin has been
specified, in which case it wraps at the specified column.
- 118 -
HyperShell Users Guide Integrated Environment
Both global margin settings and temporary margins can be used. To
bring the global margins into effect, press the Ctrl-O key. Pressing
this when any margins are in effect clears the margins. Temporary
left and right margins are brought into effect using the Ctrl-L and
Ctrl-R keys respectively. To set a left margin, start a fresh line,
enter spaces and whatever characters you wish to have in the left
margin, then press Ctrl-L. The characters you have entered will then
be entered whenever a new line is started. To set a right margin,
simply press Ctrl-R when the text cursor is at the position where the
right margin should be.
When margins are in effect, they are indicated on the bottom line.
To format existing paragraphs to the current margins, position the
text cursor immediately before, or inside, the paragraph and press
Ctrl-F. This should stop at the end of the paragraph, but may not if
the line after the paragraph contains formatting flags or inconsistent
spaces and tabs. The reformatting should allow for references
contained in the text, but cannot allow for special formatting or
hidden text flags, so it should be used with care. It is a good idea
to save your edits before undertaking any formatting in case it goes
wrong.
7.9.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 (or
BACKSPACE) key and the cursor pad DEL key.
The current line can be deleted using the Ctrl-K key. The deleted
line can be re-inserted, at the same or a different location, using
the Ctrl-U key.
Ranges of lines can be deleted by selecting one end with Function key
5, then positioning at the other end of the inclusive range and
pressing Function key 6. The deleted lines can be inserted elsewhere
using Function key 7.
7.9.4 Copying and importing
As a range of deleted lines are retained until another item is edited,
text can be moved between items in the paste buffer.
Another way of moving text is to copy another item into the end of the
current item, and move the required text where you want it. The Ctrl
shifted Function keys provide a range of item types for appending, as
follows:-
- 119 -
Integrated Environment HyperShell Users Guide
Append item to edit buffer
+-------------------------------------------+
| Ctrl F4 | Frame selected from contents |
| Ctrl F5 | Global item selected from list |
| Ctrl F6 | Local item selected from list |
| Ctrl F7 | Text file |
| Ctrl F8 | Captured text screen |
| Ctrl F9 | Text screen with attributes |
+-------------------------------------------+
The append text screen functions allow text screens captured from
other programs to be imported to the edit buffer. The `with
attributes' interprets the screen attributes and inserts formatting
flags to give the text the correct colours. Certain characters which
might cause HyperShell some embarrassment are converted to near
equivalents, and extra `$' and `~' characters are inserted to escape
these.
If a screen is imported for use as a full frame, it should have the
end of the last line trimmed so that it will not scroll when
displayed. Also the frame title should start with a `)' character to
suppress HEADER and FOOTER display.
7.9.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 its presence.
Flagging words
Shifted Function keys are provided to place reference flags around the
word in which the text cursor is placed. These are as follows:-
Add reference flags to current word
+-----------------------------------------+
| Shift F1 | Flag as Frame Step | ~f |
| Shift F2 | Flag as Frame Reference | ~F |
| Shift F3 | Flag as Global Note | ~N |
| Shift F4 | Flag as Local Note | ~n |
| Shift F5 | Flag as Global Menu | ~M |
| Shift F6 | Flag as Local Menu | ~m |
| Shift F7 | Flag as Global Script | ~S |
| Shift F8 | Flag as Local Script | ~s |
| Shift F9 | Flag as Action | ~A |
| Shift F10| Flag as Input Field | ~I |
+-----------------------------------------+
- 120 -
HyperShell Users Guide Integrated Environment
Adding cross references
The most comfortable way of adding a reference is to select the item
to be referenced from a list. This has the double advantage of saving
you the trouble of remembering and typing the items name in, and of
ensuring that the reference exists and is spelt correctly. Ctrl
shifted Function keys provide the three main lists:-
Select reference directly from list
+-------------------------------------------+
| Ctrl F1 | Select frame as reference |
| Ctrl F2 | Select Global item as reference |
| Ctrl F3 | Select Local item as reference |
+-------------------------------------------+
Automatic referencing
Automatic referencing is available on the Alt shifted Function keys.
These are as follows:-
Autoreference edit buffer
+------------------------------------------+
|Alt F1 Autoreference using frame names |
|Alt F2 Autoreference using global notes |
|Alt F3 Autoreference using local notes |
+------------------------------------------+
Clearing references
One problem with autoreferencing is `false references'. These are
where a word or phrase is flagged incorrectly as a reference. If this
happens, the reference flags can be removed from a string by placing
the text cursor in the reference and pressing Ctrl-W.
Checking references
When you have added your own reference flags, it is useful to check to
see if they are correct. This is done very easily by simply pressing
Ctrl-V. This causes the edit buffer to be checked, and any incorrect
references or other irregularities will be reported.
If no errors are reported, you do not have any problems. If errors
are reported, the line will be displayed, along with the line number
and a warning or error message. If you have a lot of errors, they
will most probably scroll off the screen, so you will have to tackle
the final ones first.
It is a good idea to run this check just before you save and exit the
item edit.
- 121 -
Integrated Environment HyperShell Users Guide
7.9.6 Searching and replacing
A search can be made for a string in the edit buffer. This is done by
pressing Alt shifted F6. This prompts for a string, then searches
forwards in the buffer for that string.
To search again for the same string, the Alt shifted F5 key may be
pressed.
One operation which is often necessary is to replace all occurrences
of one string with another. The Alt shifted F4 key provides a simple
search and replace function.
Search and Search / Replace
+------------------------------------------+
|Alt F4 Search and replace strings |
|Alt F5 Search for next occurrence |
|Alt F6 Search for string |
+------------------------------------------+
7.9.7 Other functions
Other functions may be mapped to certain control keys.
ESCAPE
The ESCAPE key is usually mapped to a menu of edit operations by the
edit control file, and some options provided on this menu may lead to
other menus. The menu must be configured for this to work.
If a mouse is connected to the system, the RIGHT button is usually
mapped to this operation as well. Mapping the ESCAPE key to another
function will also cause the mouse to use that function. The mouse
buttons may be independently mapped, however.
Function key 1
This usually presents a menu of notes, which provide help information
and graphic maps for character selection using the HOME key. The menu
must be configured for this to work.
7.9.8 Other default mappings
Function key 2
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.
- 122 -
HyperShell Users Guide Integrated Environment
Function key 3
This key is provided as an easily mapped key for your own functions.
It is by default mapped to the `check buffer' function. To re-map the
key, the edit mode variable `0' should be set to an edit mode function
sequence (see the chapter on configuring the environment).
Function key 4
This causes the current position in the edit buffer to be swapped with
that set by the `mark' function (Function key 5).
Function key 5
This sets a `mark' at the current line (and character position) used
by other functions such as the cut and paste facilities and the swap
with mark function.
Function key 6
This cuts all lines from and including the `mark' line 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 256 (around 10 full
screens). The message "Too many lines - not cut!" is displayed if
this is exceeded, and the area is left unchanged. If this happens,
reduce the size of the area and cut it in stages.
Function key 7
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.
Function key 8
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.
Function key 9
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.
Confirmation is requested before this is done.
Function key 10
This applies the changes made during the edit to the item being
edited, and returns to the frame display. If in VIEW mode, the buffer
is written to EDITBUFF.SAV and the program remains in VIEW mode.
- 123 -
Integrated Environment HyperShell Users Guide
Alt shifted F9
This gives an escape to the DOS shell, to allow small tasks to be
performed such as copying a text file for appending to the edit
buffer.
Keypad keys
+---------------------------------------------------------+
|Home | moves cursor to the start of the current line|
|End | moves cursor to the end of the current line |
|Ctrl-Home | moves cursor to the start of the current word|
|Ctrl-End | moves cursor to the end of the current word |
|Ctrl-Right| deletes chars from current to end of line |
|Ctrl-Left | deletes chars before current on current line |
|Ctrl-PgUp | joins current line to next line |
|Ctrl-PgDn | deletes the whole current line |
|Ins | toggles INSERT / OVERWRITE |
|Del | deletes current character |
|Backspace | deletes previous character |
+---------------------------------------------------------+
Control keys
+--------------------------------------------------+
|^A | open new line After current |
|^B | open new line Before current |
|^D | Delete inline (from ^X position) |
|^E | Enter EDIT command |
|^F | reformat paragraph |
|^G | Toggle flag interpretation |
|^J | Join current line to next line |
|^K | Kill (delete) current line |
|^L | Set temporary Left margin |
|^N | Save edit buffer to file EDITBUFF.SAV |
|^O | Toggle margins (clear temporary margins) |
|^Q | Quote verbatim character (next char typed) |
|^R | Set temporary Right margin |
|^T | Toggle cursor Tracking (actual/visible char) |
|^U | Undelete line |
|^V | Verify (check) buffer |
|^W | Wipe reference flags |
|^X | Mark start for inline cut (^D to cut) |
|^Y | paste in line |
|^Z | duplicate character from mouse position |
+--------------------------------------------------+
- 124 -
