Here begins Part 2 of the extensive Devpac Docs. Again, it was
typed by the Animal House and edited by Sewer Rat.
CHAPTER 2
SCREEN EDITOR
INTRODUCTION
To enter and assemble your programs you need an editor of
some sort and an assembler. GenST combines both of these functions
together in one integrated program, giving a GEM - driven full-
screen editor and a fast, full specification assembler. It also
allows you to run your assembled programs directly from memory
without having to quit the program or do a disk access and to
access a debugger at the press of a key. The fact that all these
features are combined in one program means that the correcting
errors and making changes is as fast as possible without the need
for slow disk accesses and other programs.
This chapter details the use of the editor and how to
assemble programs - it does not detail the assembler or the
debugger themselves, they are covered in the following chapters.
To run GenST, double click on the GENST2.PRG icon from the
Desktop. When it has loaded a menu bar will appear and an empty
window will open, ready for you to enter and assemble your
programs.
THE EDITOR
A text editor is a program which allows you to enter and
alter lines of text, store them on disk, and load them back again.
There are two types of text editors: line editors, which treat
each line separately and can be very tricky to use, and screen
editors, which display your text a screen at a time. The latter
tend to be much easier to use.
The editor section of GenST is a screen editor which allows
you to enter and edit text and save and load from disk, as you
would expect. It also lets you print all or some of your text,
search and replace text patterns and use any of the ST's desk-
accessories. It is GEM-based, which means it uses all the user-
friendly features of GEM programs that you have become familiar
with on your computer such as windows, menus and mice. However, if
you're a die-hard, used to the hostile world of computers before
the advent of WIMP's, you'll be pleased to know that you can do
practically everything you'll want to do from the keyboard without
having to touch a mouse.
The editor is 'RAM-based', which means that the file you are
editing stays in memory for the whole time, so you don't have to
wait while your disk grinds away loading different sections of the
file as you edit. As the ST range has so much memory, the size
limitations often found in older computer editors don't exist with
GenST; if you have enough memory you can edit files of over 300k
(though make sure your disk is large enough to cope with saving it
if you do !). As all editing operations, including things like
searching, are RAM based they act blindingly quickly.
When you have typed in your program it is not much use if you
are unable to save it to disk, so the editor has a comprehensive
range of save and load options, allowing you to save all or part
of the text and to load other files into the middle of the current
one, for example.
To get things to happen in the editor, there are various
methods available to you. Features may be accessed in one or more
of the following ways;
Using a single key, such as a Function or cursor key:
Clicking on a menu item, such as SAVE:
Using a menu shortcut, by pressing the Alternate key
(subsequently referred to as Alt) in conjunction with
another such as Alt-F for Find:
Using the control key (subsequently referred to as Ctrl) in
conjunction with another, such as Ctrl-A for cursor word
left:
Clicking on the screen, such as a scroll bar.
The menu short cuts have been chosen to be east and obvious
to remember, while the Ctrl commands are based on those used in
Wordstar, and many other compatible editors since.
If at any time you get stuck, pressing the HELP key will
bring up a comprehensive display of the keys for functions not
visible in menus.
A FEW WORDS ABOUT DIALOGUE BOXES
The editor makes extensive use of dialogue boxes, so it is
worth recapping how to use them, particularly for entering text.
The editor's dialogue box contains buttons, radio buttons, and
editable text.
Buttons may be clicked on with the mouse and cause the
dialogue box to go away. Usually there is a default button, shown
by having a wider border than the others. Pressing RETURN on the
keyboard is equivalent to clicking on the default button.
Radio buttons are groups of buttons of which only one may be
selected at a time - clicking on on automatically de-selects all
the others.
Editable text is shown with a dotted line, and a vertical bar
marks the cursor position. Characters may be typed in and
corrected using the Backspace, Delete and cursor keys. You can
clear the whole edit field by pressing the ESC key. If there is
more than one text field in a dialogue box, you can move between
them using the up and down cursor keys or by clicking near them
with the mouse.
Some dialogue boxes allow only a limited range of characters
to be typed into them - for example the Goto Line dialogue box
only allows numeric characters (digits) to be entered.
ENTERING TEXT AND MOVING THE CURSOR
Having loaded GenST, you will be presented with an empty
window with a status line at the top and a flashing black block,
which is the cursor, in the top left-hand corner.
The status line contains information about the cursor
position in the form of Line Column offsets as well as the number
of bytes of memory which are free to store your text. Initially
this is displayed as 59980, as the default text size is 60000
bytes. You may change this default if you wish, together with
various other options, by selecting Preferences, described later.
The missing 20 bytes are used by the editor for internal
information. The rest of the status line area is used for error
messages, which will usually be accompanied with a 'ping' sound to
alert you. Any message that gets printed will be removed
subsequently when you press a key.
To enter text, you type on the keyboard. As you press a key
it will be shown on the screen and the cursor will be advanced
along the line. If you are a good typist you may be able to type
faster than the editor can re-display the line; if so, don't
worry, as the program will not lose the keystrokes and will catch
up when you pause. At the end of each line you press the Return
key (or the Enter key on the numeric pad) to start the next line.
You can correct your mistakes by pressing the Backspace key, which
deletes the character to the left of the cursor, or the Delete
key, which removes the character the cursor is over.
The main advantage of a computer editor as opposed to a
normal typewriter, is its ability to edit things you typed a long
time ago. The editor's large range of options allow complete
freedom to move around your text at will.
CURSOR KEYS
To move the cursor around the text to correct errors or enter
new characters, you use the cursor keys, (the arrows). If you move
the cursor past the right-hand end of the line this won't add
anything to your text, but it you type some text at the point the
editor will automatically add the text to the real end of the
line. If you type in long lines the window display will scroll
sideways if necessary.
If you cursor up at the top of the window the display will
either scroll down if there is a previous line, or print the
message Top of file in the status line. Similarly if you cursor
down off the bottom of the window the display will either scroll
up if there is a following line, or print the message End of file.
You can move the cursor on a character basis by clicking on
the arrow boxes at the end of the horizontal and vertical scroll
bars.
For those of you used to Wordstar, the keys Ctrl-S, Ctrl-D,
Ctrl-E and Ctrl-X work in the same way as the cursor keys.
To move immediately to the start of the current line, press
Ctrl (left arrow), to move to the end of the current line press
Ctrl (right arrow).
To move the cursor a word to the left, press Shift (left
arrow) and to the right press Shift (right arrow). You cannot move
a cursor past the end of a line with this. A word is defined as
anything surrounded by a space, a tab or a start or end of line.
The keys Ctrl-A and Ctrl-F also move the cursor left and sight on
a word basis.
To move the cursor a page up, you can click on the upper grey
part of the vertical scroll bar, or press Ctrl-R or Shift (up
arrow). To move the cursor a page down, you can click on the lower
grey part of the scroll bar, or press Ctrl-C or Shift (down
arrow).
If you want to move the cursor to a specific position on the
screen you move the mouse pointer to the required place and click
(There is no Wordstar equivalent for this feature!)
TAB KEY
The Tab key inserts a special character (ASCII code 9) into your
text, which on the screen looks like a number of spaces, but is
rather different. Pressing Tab aligns the cursor onto the next
'multiple of 8' column, so if you press it at the start of a line
(column 1) the cursor moves to the next multiple of 8 + 1, which
is column 9. Tabs are very useful indeed for making items line up
vertically and its main use in GenST is for making instructions
line up. When you delete a tab the line closes up as if a number
of spaces had been removed. The advantage of tabs is that they
only take up 1 byte of memory, bat can show on screen as many
more, allowing you to tabulate your program neatly. You can change
the tab size before or after loading GenST using the Preferences
command described shortly.
BACKSPACE KEY
The Backspace key removes the character to the left of the
cursor. If you backspace at the very beginning of a line it will
remove the 'invisible' carriage return and join the line to the
end of the previous line. Backspacing when the cursor is past the
end of the line will delete the last character on the line, unless
the line is empty in which case it will re-position the cursor on
the left of the screen.
DELETE KEY
The Delete key removes the character under the cursor and has
no effect if the cursor is past the end of the current line.
GOTO A PARTICULAR LINE
To move the cursor to a particular line in the text, click on
Goto line.. from the Options menu, or press Alt-G. A dialogue box
will appear allowing you to enter the required line number. Press
Return or click on OK button to go to the line or click on Cancel
to abort the operation. After clicking on OK the cursor will move
to the specific line, re-displaying if necessary, or give error
End of file if the line does't' exist.
Another fast way of moving around the file is by dragging the
slider on the vertical scroll bar, which works in the usual GEM-
like fashion.
GOTO TO TOP OF FILE
To move to the top of the text, click on Goto Top from the
Options menu, or press Alt-T. The screen will be re-drawn if
required starting from line 1.
GOTO END OF TEXT
To move the cursor to the start of the very last line of
text, click on Goto Bottom, or press Alt-B
QUITTING GENST
To leave GenST, click on Quit from the File menu, or press
Alt-Q. If changes have been made to the text which have not been
saved to disk, an alert box will appear asking for confirmation.
Clicking on Cancel will return you to the editor, while clicking
on OK will discard the changes and return you to the Desktop.
DELETING TEXT
DELETE LINE.
The current line can be deleted from the text by pressing
Ctrl-Y.
DELETE TO END OF LINE.
The text from the cursor position to the end of the current line
can be deleted by pressing Ctrl-Q. (This is equivalent to the
Wordstar sequence Ctrl-Q Y).
UNDELETE LINE
When a line is deleted using either of the above commands it
is preserved in an internal buffer, and can be re-inserted into
the text by pressing Ctrl-U, or the Undo key. This can be done as
many times as required, particularly useful for repeating similar
lines or swapping over individual lines.
DELETE ALL TEXT
To clear out the current text, click on Clear from the File
menu, or press Alt-C. If you have made any changes to the text
that have not been saved onto the disk, a confirmation is required
and the requisite alert box will appear. Clicking on OK will
delete the text, or Cancel will abort the operation.
DISK OPERATIONS
GEM FILE SELECTOR BOX
(This section has been left out as it is common knowledge to
anyone who uses their ST, if you want to read it, it is the same
details as contained in your Atari manual)
** In all pre-blitter versions of the ST ROM's there is a bug
which means that if you press _ (underline) when the cursor is in
the Directory string the machine will crash!!
SAVING TEXT
To save the text you are currently editing, click on Save As
from the File Menu, or press Alt-S. The standard GEM File Selector
will appear, allowing you to select a suitable disk and filename.
Clicking OK or pressing Return will then save the file onto the
disk. If an error occurs a dialogue box will appear showing a TOS
error number, the exact meaning of which can be found in Appendix
A.
If you click on Cancel the text will not be saved. Normally
if a file exists with the same name it will be deleted and
replaced with the new version, but if Backups are selected from
the Preferences options then any existing file will be renamed
with extension .BAK (deleting any existing .BAK file) before the
new version is saved.
SAVE
To save the file you can click on the Save option on the File
menu, or press Shift-Alt-S, and it will use the old name.
LOADING TEXT
To load a new file, click on Load from the File menu, or
press Alt-L.
INSERTING TEXT
If you want to read a file from disk and insert it at the
current position in your text click on Insert File from the File
menu or press Alt-L
SEARCHING AND REPLACING TEXT
To find a particular section of text click on Find from the
Search menu, or press Alt-F. A dialogue box will appear, allowing
you to enter the Find and Replace strings. If you click on Cancel,
no action will be taken; if you click Next (or press Return) the
search will start forwards, while clicking on Previous will start
the search backwards. If you do not wish to replace, leave the
Replace string empty. If the search was successful, the screen
will be re-drawn at that point with the cursor positioned at the
start of the string. If the search string could not be found , the
message Not Found will appear in the status area and the cursor
will remain unmoved. By default the search is always case-
independant, so for example if you enter the search string as test
you could find the words TEST, Test or test. If you click on the
Upper & Lower case Different button the search will be case
dependant.
To find the next occurrence of the string click on Find Next
from the Search menu, or press Alt-F. The search starts at the
position just before the cursor.
To search for the previous occurrence of the string click on
Find Previous from the Search menu, or press Alt-P.
Having found an occurrence of the required text, it can be
replaced with the Replace string by clicking on Replace from the
Search menu, or pressing Alt-R. Having replaced it, the editor
will then search for the next occurrence.
If you wish to replace every occurrence of the find string
with the replace string from the cursor position onwards, click on
Replace All from the Search menu. During the global replace the
ESC key can be used to abort and the status area will show how
many replacements were made. There is deliberately no keyboard
equivalent for this to prevent it being chosen accidentally.
BLOCK COMMANDS
A Block is a marked section of text which may be copied to
another section, deleted, printed or saved onto disk. The function
keys are used to control blocks.
MARKING A BLOCK
The start of a block is marked by moving the cursor to the
required place and pressing key F1. The end of a block is marked
by moving the cursor and pressing key F2. The start and end of the
block do not have to be marked in a specific order - if it is more
convenient you may mark the end of the block first.
A marked block is highlighted by showing the text in reverse.
While you are editing a line that is within a block this
highlighting will not be shown but will be re-displayed when you
leave that line or choose a command.
SAVING A BLOCK
Once a block has been marked, it can be saved by pressing key
F3. If no block is marked, the message What blocks! will appear.
If the start of the block is textually after its end the message
Invalid block! will appear. Both errors abort the command.
Assuming a valid block has been marked, the standard GEM file
selector will appear, allowing you to select a suitable disk and
filename. If you save the block with a name that already exists
the old version will be overwritten - no backups are made with
this command.
COPYING A BLOCK
A marked block may be copied, memory permitting, to another
part of the text by moving the cursor to where you want the block
copied and pressing key F4. If you try to copy a block into a part
of itself, the message Invalid block will appear and the copy will
be aborted.
DELETING A BLOCK
A marked block may be deleted from the text by pressing
Shift-F5. The shift key is deliberately required to prevent it
being used accidentally. A deleted block is remembered, memory
permitting, in the block buffer, for later use.
** This is on a different key to that used in GenST in versions
before 2.0.
COPY BLOCK TO BLOCK BUFFER
The current marked block may be copied to the block buffer,
memory permitting, by pressing Shift-F4. This can be very useful
for moving blocks of text between different files by loading the
first, marking the block, copying it to the block buffer then
loading the other file and pasting the block buffer into it.
PASTING A BLOCK
A block in the block buffer may be pasted at the current
cursor position by pressing F5.
** The block buffer will be lost if the edit buffer size is
changed or an assembly occurs.
PRINTING A BLOCK
A marked block may be sent to the printer by printing on
Print Block from the File menu, or by pressing Alt-W. An alert box
will appear confirming the operation and clicking on OK will print
the block. The printer port used will depend on the port chosen
with the Install Printer desk accessory, or will default to the
parallel port. Tab characters are sent to the printer as a
suitable number of spaces, so the net result will normally look
better than if you print the file from the Desktop.
If you try to print when there is no block marked, the whole
file will be printed.
Block markers remain during all editing commands, moving
where necessary, and are only reset by the commands New, Delete
Block, and Load.
MISCELLANEOUS COMMANDS
ABOUT GENST2
If you click on About GenST2.. from the Desk menu, a dialogue
box will appear giving various details about GenST. Pressing
Return or clicking OK will return you to the editor.
HELP SCREEN
The key equivalents for the commands not found in menus can be
seen by pressing the HELP key, or Alt-H. A dialogue box will
appear showing the Wordstar and function keys, as well as the free
memory left in the system.
PREFERENCES
Selecting Preferences.. from the Options menu will produce a
dialogue box allowing you to change several editor settings.
TABS
By default, the tab setting is 8, but this may be changed to
any value from 2 to 16.
TEXT BUFFER SIZE
By default the text buffer size is 60000 bytes, but this can
be changed from 4000 to 999000 bytes. This determines the largest
file size that can be loaded and edited, Care should be taken to
leave sufficient room in memory for assembly or running MonST -
pressing the HELP key displays free system memory, and for
assembly or debugging this should always be about 100k bytes.
Changing the editor work-space size will cause any text you are
currently editing to be lost, so a confirmation is required if it
has not been saved.
NUMERIC PAD
The Numeric Pad option allows the use of the numeric keypad
in an IBM-PC-like way allowing single key presses for cursor
functions, and defaults to Cursor pad mode. The keypad works as
shown below,
7 START 8 (UP) 9 PAGE UP
OF LINE
4 (LEFT) 5 6 (RIGHT)
1 END OF 2 (DOWN) 3 PAGE DOWN
LINE
BACKUPS
By default the editor doesn't make backups of programs when
you save them, but this can be turned on by clicking on the Yes
radio button.
AUTO INDENTING
It can be particularly useful when editing programs to indent
subsequent lines from the left, so the editor supports an auto-
indent mode. When active, an indent is added to the start of each
new line created when you press RETURN. The contents of the indent
of the new line is taken from the white space (i.e. tabs and/or
spaces) at the start of the previous line.
CURSOR
By default the GenST cursor flashes but this can be disables
if required.
LOAD MONST
By default a copy of MonST is loaded during the editor
initialisation, allowing it to be accessed at the press of a key.
Should this not be required it can be disabled with this option.
This will save around 24k of memory. The new value of this option
will only have an effect if you save the preferences and re-
execute the editor.
SAVING PREFERENCES
If you click on the Cancel button any changes you make will
be ignores. If you click on the OK button the changes specific
will remain in force until you quit the editor. If you would like
the configuration made permanent then click on the Save button,
which will create the file GENST2.INF on your disk. Next time you
run GenST the configuration will be read from that file.
In addition to saving the editor configuration the current
setting from the Assembly Options dialogue box are also saved.
ASSEMBLING & RUNNING PROGRAMS
All assembly and run options can be found on the Program menu
ASSEMBLY
To assemble the program you are currently editing click on
Assemble from the Program menu, or press Alt-A. The meaning of the
various options, together with the assembly process itself is
detailed in the next chapter. The only option covered here is the
Output option.
GenST can assemble to disk, to memory, or nowhere -
assembling to nowhere is ideal for syntax checking while assembly
to memory is much faster than to disk and good for trying things
out quickly. When you assemble to memory you have to specify the
maximum program size in the Max: entry in the dialogue box -
normally this is 20k, enough for an average program with debug or
a large program with no debug. This number determines the program
buffer size, used by the assembler to store your assembled
program. If you get the program buffer full error when you
assemble something you should change the number to be larger.
There is of course a penalty for this - the bigger the program
buffer size the smaller the amount of memory left for the
assembler itself to use while assembling your program. If the
assembler itself aborts with Out of memory it means there is not
enough left for a complete assembly - you should reduce the buffer
size, or if this still fails you will have to assemble to disk.
When you assemble to disk the program buffer size number is
ignored, giving maximum room in memory for the assembler itself.
If you haven't saved your program source code yet the file will be
based on the name NONAME.
After you click on Assembly or press RETURN the assembly
process will start, describe more fully in the next chapter. At
the end of the assembly the program will wait for a key press,
allowing you to read any messages produced, before returning you
to the editor. If there were any errors the editor will go to the
first erroneous line and display the error message in the status
bar. Subsequent errors (and warnings) may be investigated by
pressing Alt-J.
RUNNING PROGRAMS
If you click on Run or press Alt-X (eXecute) you can then run
a program previously assembled into memory. When your program
finishes it will return you to the editor. If the assembly didn't
complete normally for any reason then it is not possible to run
the program.
If your program crashes badly you may never return to the
editor, so if in doubt save your source code before using this, or
the following command.
** If only non-fatal errors occurred during assembly (e.g.
undefined symbols) you will still be permitted to run your
program, at your own risk.
PLEASE NOTE
When running a Run command from the editor the machine may
seem to 'hang up' and not run the program. This occurs if the
mouse is in the menu bar area of the screen and can be corrected
by moving the mouse. Similarly when a program has finished
running, the machine may not return to the editor. Again, moving
the mouse will cure the problem. This is due to a feature of GEM
beyond our control.
DEBUG
If you wish to debug a program previously assembled to memory
click on Debug form the Program menu, or press Alt-D. his will
invoke MonST to debug your program, including any debugging
information specified. Pressing Ctrl-C from MonST will terminate
both your program and the debugger. The screen type is determined
by the Run with GEM option, described below.
** If the Load MonST option is disabled this option is not
available and the menu is disabled.
MONST
Clicking on MonST from the Program menu, or pressing Alt-M,
will invoke MonST in a similar way to if it was invoked by double-
clicking on the program icon from the Desktop, but instantly, as
it is already in memory. You will return to the editor on
termination of the debugger. The screen type is determined by the
Run with GEM option, described below.
** If the Load MonST option is disabled this option is not
available and the menu is disabled.
RUN WITH GEM
Normally when the commands Run, Debug or MonST are used the
screen is initialised to the normal GEM type, with a blank menu
bar and patterned desktop. However if running a TOS program this
can be changed to a blank screen with a flashing cursor, by
clicking on Run with GEM, or by pressing Alt-K. A check-mark next
to the menu item means GEM mode, no check mark means TOS mode. The
current setting of this option is remembered if you Save
Preferences.
** Running a TOS program in GEM mode will look messy but work,
but running a GEM program in TOS mode can crash the machine.
JUMP TO ERROR
During an assembly any warnings or errors that occur are
remembered, and can be recalled from the editor. Clicking on Jump
to Error from the Program menu, or pressing Alt-J will move the
cursor to the next line in your program which has an error, and
display the message in the status line of the window. You can
step to the next one by pressing Alt-J again, and so on, letting
you correct errors quickly and easily. If there are no further
errors when you select this option the message No more errors will
appear, or if there are no errors at all the message What errors!
will appear.
RUN OTHER...
This option lets you run other programs from within the
editor, then return to it when they finish. Its main use is to
allow you t run programs you have assembled to disk, or to run the
linker, without having to return to the desktop and double-
clicking them. You can run both TOS and GEM programs with this
option, subject to available memory. When you click on Run
Other... you will first be warned if you have not saved your
source code, then the GEM file selector will appear, from which
you should select the program you wish to run. If it is a .TOS or
.TTP program you will be prompted for a command line, then the
screen initialised suitably.
** Screen initialisation depends on the filename extension, not
the current Run with GEM option setting.
WINDOW USAGE & DESK ACCESSORIES
THE GEM EDITOR WINDOW
The window used by the editor works like all other GEM
windows, moving it and altering it with the mouse.
DESK ACCESSORIES
If your ST system has any accessories, you will find them in
the Desk menu. If they use their own window, as Control Panel
does, you will find that you can control which window is at the
front by clicking on the one you require. For example, If you have
selected the control panel it will appear in the middle of the
screen, on top of the editor window. You can then move it around
and if you wish it to lie 'behind' the editor window, you can do
it by clicking on the editor window, which brings it in front,
then re-sizing it so you can see part of the control panel's
window behind it. When you want to bring that to the front just
click on it and the editor window will go behind. The editors
cursor only flashes and the menus only work when the editors
window is at the front.
AUTOMATIC DOUBLE CLICKING
You may configure GenST to be loaded automatically whenever a
source file is double-clicked from the desktop, using the INSTALL
APPLICATION option.
To do this you first have to decide on the extension you are
going to use for your files, which we recommend to be .S for
source files. Having done this, go to the Desktop, and click once
on GENST2.PRG to highlight it. Next click on Install Application
from the Options menu and a dialogue box will appear. You should
set the Document Type to be S (or whatever you require), and leave
the GEM radio button selected. Finally click on the OK button (if
you press Return it will be taken as Cancel).
Having done this, you will return to the Desktop. To test the
installation, double-click on a file with the chosen extension
which must be on the same disk and in the same folder as GenST
and the desktop will load GenST, which will in turn load in the
file of your choice ready for editing or assembly.
** To make the configuration permanent, you have to use the Save
Desktop option.
SAVED! DESK ACCESSORY USERS
If you use the PATH feature of the Saved! by HiSoft desk
accessory then the restriction of having your data files in the
same folder and drive as your assembler described above is not
relevant. The editor looks for the GENST2.INF configuration file
firstly in the current directory which is the folder where you
double-clicked on the data file), then using the system path.
Saving the editor preferences will put the .INF file in the same
place it was loaded from, or if it was not found then it will be
put in the current directory.
You may invoke Saved! from within the editor at any time by
pressing Shift-Clr. his will only work if the desk accessory is
called SAVED!.ACC or SAVED.ACC on your boot disk.