Welcome to the MAE assembler.

The design goal of MAE was to provide a highly integrated environment for
an editor, assembler, and debugger.  It is very easy to use, and contains
many features to save the programmer keystrokes, and development time.  It
does not take the approach of, "If I make the assembly speed fast enough,
nothing else matters."  I believe that only a small portion of a project's
development time is spent waiting for the assembler to assemble your file.
Therefore, programming efforts were mainly concentrated on making the
editing and debugging processes easier.  MAE is fairly quick, but not the
fastest assembler available.  For example, the editor module of MAE is
2850 lines of source, and assembles to a disk file in 18 seconds.

MAE uses the standard E: device to allow easy compatibility with the XEP80
and other 80 column devices or software drivers.  The speed of Atari's
built-in 40 column device is not the greatest, and so you will also find
the HYPER E: screen accelerator on the disk.  This will more than double
the screen performance when it is installed, and it is highly recommended.
MAE also includes software drivers that allow 64 column and 80 column
editing on a high-speed Gr.8 screen.  Thanks goes to Itay Chamiel for his
work on these drivers.

I am always interested in hearing comments or suggestions about MAE.  You
can reach me at:
John Harris
45346 Graceway Dr
Ahwahnee CA 93601
USA
internet: jharris@poboxes.com

Here are some of the features of the MAE development system.

MAE provides an excellent full-screen type editor with many features such
as key macros, automatic 'JSR' and return to subroutine labels, block moves
and copies, and multiple undo.

Compatible with the XEP80, and probably most other video boards that
provide an E: handler interface.  Software drivers for 64 and 80 column
screens are also provided.

High level of integration between editor, assembler, and debugger.  The
editor can take you directly to lines that had assembly errors.  The
debugger can reference labels in the symbol table and assemble single
program lines.

Very efficient -- it will save you a lot of typing.

True local labels that are referenced between global labels.

Full text substitution macros.

Can assemble directly to bank select memory or bank select cartridges.

Uses very little system RAM.  Most of the code resides in bank select
memory.

Full 65816 and 24 bit support.

- MEMORY USAGE AND CONFIGURATION -

This assembler is designed to run in up to 3 banks of the extended memory
available on the 130XE or other memory expanded Atari.  The bank numbers
are configurable.  A portion of the assembler must reside outside of bank
select RAM, and in this version, it will occupy $B700-$BBFC.

Memory usage for the source file and symbol table is configurable.  In
addition, they can use bank select RAM for addresses within the $4000-$7FFF
range, which keeps this area in main RAM free for the user.  Having the
symbol table in bank select RAM has one other benefit.  It will usually stay
intact so that the labels can be used from the debugger.  The default values
for memory usage will place the symbol table in one bank by itself, and the
source buffer from LOMEM to $B6FF, with the segment from $4000-$7FFF in
another bank of extended RAM.  $4000-$7FFF in main RAM is free to the user,
unless running the 64 or 80 column handlers which use part of this space,
from $5600-$7FFF.

This assembler isn't designed for a 64K machine, but it can be configured
to operate in a limited fashion.  Because the bulk of the code sits at
$4000-$7FFF, it is right in the middle of RAM if you don't have bank
select memory.  The best you will be able to do, is set the text buffer
from $8000-$B6FF, and the symbol table from LOMEM to $3FFF.  That will
only give you about 14K for your text buffer, and your symbol table may
not always be available for the debugger, but otherwise, all functions
should work as described.  See INSTALL.DOC for more details.

Zero page memory is saved and restored from the editor and assembler, so
that they will effectively leave all of ZP available to the user.

Buffer memory addresses and several configurable parameters are stored at
the beginning of the program file.  The parameters are located at +3 bytes
from the start address, which will be +9 bytes when counting the DOS binary
header.  A utility, CONFIG.COM, is now provided to edit these parameters.
A description of them follows.  (Words are 6502 standard Lo,Hi)

Word - Text buffer start adr.  If 0, the editor will use MEMLO.  (Default)
Word - Text buffer end.  If 0, the editor will use MEMTOP.  Default $B6FF.
Word - Symbol table start adr.  Default $4000, in bank select memory.
Word - Symbol table end.  Default $7EFF.  (The code for symbol table search
       is at $7F00).
Byte - Assembly CPU mode.  0=65816, $80=6502.  Other bits may be used in
       the future.
Byte - Editor mode.  Two bits are currently defined:
       When bit 7 is on ($80), Insert mode is active.
       When bit 6 is on ($40), spaces are converted into Tabs.
       When bit 5 is on ($20), editor will start with Caps lock on.
       Other bits may be used in the future.
Byte - Debugger mode.  Currently unused, but reserved for future options.
3 Bytes - Tab settings for Assembly code fields.
Byte - When drawing the screen for a particular location, such as a
       Find or Goto command, this byte sets the screen row where the
       desired line will be located.  If you set this to 0, the line
       will be on the top row.  $0C will put the line in the middle
       of the screen.  Default is 6.
Byte - # of lines the PgUp & PgDn command will move by.  Setting
       this to $18 gives single screen paging.  If you normally use
       scrolling for short moves, you can set this value to something
       like $60 to jump through the file in larger steps.
Byte - Line length saved in the Undo buffers.  Default is 39.  You
       can increase this to 79, if you want entire 80 column lines saved.
       You can also decrease this number to something like 25, if you
       want to increase the number of history buffers without using
       extra memory.  You would only lose the comment field for any
       restored lines.
Byte - # of Undo buffers.  This number sets how many lines of history
       can be undo'ed.  Default is 16.  Multiplied by the number above,
       equals the total size needed for undo storage, located at the end
       of the text buffer.
Byte - Sets what bank of extended memory to put the assembler.  It should
       be a value appropriate for the $D301 register.  Default is $E3.
Byte - Sets what bank to put the symbol table.  Default is $E7.  Be aware
       that there is a small piece of code from $7F00-$7FFF that gets
       stored in the same bank as the symbol table.
Byte - Sets what bank to put part of the source text.  Default is $EB.
       If source memory is configured from LOMEM to $B6FF, the segment
       from $4000-$7FFF will be put in this bank, leaving that region of
       main RAM free for object code or other uses.
2 Bytes - An optimistic number of bytes for future expansion.
String - Default drive and dir spec.  Must be in the form Dn:?????,
       like "D3:*.*", or "D3:*.S" if you want dir listings to only
       show a certain file type.  Filenames for loading and saving
       do not require a full "Dn:" filespec.  If you type just a
       name, it will be preceded with the default drive selected here.

- THE MAIN MENU -

The program will display the main menu once it has loaded.  During an
editing session, the Esc key will return to this menu, and Esc will also
return to the editor when you are in the menu.

Main Menu Commands:

A - Assemble current file.  Hold the Shift key when pressing A to turn on
    the assembler listing.  The only current way to send an assembler
    listing to the printer, is to first use the "O" debugger command to
    enable output echo to the printer.

B - Break to the monitor.  Actually issues a 00 BRK instruction.

D - Go to DOS.  If you return to the editor by running at the start address,
    the source file will still be intact.  This is automatic in SpartaDOS
    by using the RUN command.  For other DOSes, you will need to supply the
    starting address which is currently $B800, but may change in later
    versions.

L - Load file.  You do not need to type an entire filespec.  The default
    drive 'Dn:' will be prepended if the entered name doesn't have a ':'.
    Press Shift-L to append to the end of an existing file.

M - Macro load and save.  The contents of the keyboard macro buffer can be
    saved to and loaded from disk files.  This allows you to create useful
    key macros and save them to disk for later use.

P - Do Pass 2 only of the assembly.  A full assembly must have already been
    performed, and then this function may be used if the source code was
    changed in such a way that didn't effect any label addresses.  This can
    save a lot of assembly time, but please do not use it unless you
    understand what it does and are certain that no label addresses have
    been changed since the last assembly.

S - Save File.  Save displays the last loaded filename.  Press Return to
    accept it, or backspace and change.  Press Shift-S to save a marked
    text block.  To do this, mark the starting line with ^Z, then move to
    the ending line and enter the Esc-Shift-S command.  To print a file or
    text block, you may need to convert the text to spaces only, and then
    save to P:.

T - Tab convert.  It will prompt to convert to Tabs or Spaces.  Tab
    converted text will have $7F TAB characters for any sequences of
    spaces that can be compressed.  The conversion is done from back to
    front for best speed, but it can still take awhile.  It is also
    possible to run out of RAM when converting to spaces.  After this
    command is entered, the editor will remain in the specified mode.  In
    other words, if you do a tab convert to spaces, all future entered
    lines will remain in an expanded space format.

V - (Value)  Will allow you to enter any expression, and then displays the
    calculated value in both hex and decimal.  This can be handy for
    getting the value of labels, or as a simple calculator.

X - Perform cross reference listing.  The source file must already have
    been assembled with the A command.  It allows you to enter a label name
    to start from, or just press return to create a cross reference for the
    entire symbol table.  Be prepared for this to take awhile.  This is a
    simple implementation that requires a full pass of assembly for each
    label.  On the positive side, it doesn't require any memory to build an
    XRef table, and so generating an XRef on large files should not have
    any problems running out of memory.  Plus, being able to specify label
    names directly makes it very easy, and much quicker, to get a report
    for one or two labels of immediate interest.

1-9 Get directory, and set default drive.  If you just want to change the
    default drive without getting a dir listing, press Esc after pressing
    the desired number.

Shift-Clear - Clear text buffer.

- EDITOR FILE FORMAT -

The editor saves files in straight ATASCII.  It can either keep all spaces
expanded, or can use $7F TAB characters to reduce the size of the file.
The text can be freely converted between these formats.  TAB compression
and expansion is done on a line by line basis while you are editing, which
is different from the way most editors handle TABs.  While you are editing
a line, TAB characters are not present, and the line will edit in the same
way as if it had only spaces.  When the line is saved back into the file,
the program will see if it can convert any sequences of spaces into TABs,
based on the configured TAB fields.  TABs are not rigidly enforced.
Meaning, if you slide a comment field a little to the left to make more
room, that spacing will be retained, and that particular place simply won't
be TAB converted.  Thus, it is simply a manner of saving memory and file
space.  The editor will actually run faster with the TAB setting on,
especially with the XEP80.

The editor allows line lengths up to 79 columns, and will scroll
horizontally for displays that are narrower than this.

- EDITING COMMANDS -

Standard Atari editing keys apply, with a few exceptions.  Clr & Set Tab
have no effect.  Use the configure bytes to change tabs.  Pressing the
Caps key without Shift will always set lower case instead of toggling.
Use Shift-Caps to set upper case.  1200XL function keys, as well as the
standard Atari arrow keys, can be used to move the cursor.

Return will insert a new line if pressed at the end of the current line.
Otherwise, it will just move to the line below.  Return does not break a
line in the middle, which works out better when entering source code.

In the following tables, a "^" symbol means to press Control along with the
key after the "^".  "S^" means press both the Shift and Control keys.

- MOVING AROUND -

S^Up Scroll Up
S^Dn Scroll Down.  These two commands are handy, because they scroll
     immediately, without waiting for the cursor to reach the screen's
     edge.
S^<  Page up by configurable # of lines
S^>  Page Down
^,   Start of line
^.   End of line
^T   Top of file
^B   Bottom of file
^S   Set mark at current location
^M   Go to Mark
^G   Goto line number.  When entering the line number at the prompt, you
     can also enter a '+' or '-' as the first character to move a number
     of lines relative to the current location.

- FIND & REPLACE -

^F   Find text -- not case sensitive.  '?' can be used as a wildcard.
^?   Change the wildcard character.  After issuing the command, press
     any other key to set the wildcard to that character.  The wildcard
     character is shared between the editor and debugger, and changing
     it within either module will affect uses in both modules.
S^F  Find by searching backwards towards the start of the file.
^R   Replace -- forward direction only.  It will ask for a Find string
     and then a Replace string.  For all matches of the find string, the
     editor will display an inverse '>' symbol in front of the occurrence.
     You may press Y to replace it, N to skip it, A to replace all
     occurrences to the end of the text, or Esc to abort.
     Max length for Find or Replace is 15 characters.
^N   Next.  If the previous operation was a replace, then you will be in
     the prompted replace mode if the string is found.  Otherwise, if the
     previous operation was a Find, then you will simply be taken to the
     next occurrence.
^P   Find Previous match, by searching backwards.
^L   Enter a label name, and the editor will jump to where the label is
     defined.  (By searching from the first column only.)
^J   The editor's version of a JSR.  It looks at the operand field of the
     current line, and jumps to where that label is defined.  It also
     sets a mark at the current line so that you can return with a ^H.
     The use of this function is not limited to JSR instructions.  JMPs,
     branches, even data variable locations can be traced with this
     command.  Basically, for any line that contains an operand field,
     ^J will attempt to find the location where that label is defined.
^H   Return to previous position where a ^J command was entered.
     ^H is also used to jump to locations that gave assembly errors.
     During the assembly, up to 16 error positions will be remembered.
     All bookmarks, and marks set from the ^J and error position
     reporting, will auto-adjust to any changes in the source text, so
     that they will always point to the correct line in the source file.

- BLOCK MOVES & COPIES -

^Z   Set block start.
^X   Cut from block start to current line, in a forwards direction only.
     If you find you want to mark a block backwards, the easiest way to
     do this, is to set the mark at the current line, then move backwards
     to the start of the block.  Press ^Z, then press ^M to return to
     where you started, and give the ^X or ^C command.  A clear to end of
     file operation can be done by pressing the keys, ^Z, ^B, ^X.
^C   Copy text from block start to current line, into the cut buffer.
     The text is left unchanged.
^V   Paste the cut buffer at current line.
^D   If there is a ^Z block mark set, ^D will duplicate the text block.
     Effectively, it does a ^C followed by a ^V.  Because this process
     clears the ^Z mark, multiple presses of ^D will not produce multiple
     copies of the same block.  Use ^V to paste additional blocks.  If
     there is no ^Z mark, then ^D will duplicate only the current line.

- KEY MACROS -

^W   (Write) Begin key macro recording.  When done, press ^3.  Up to 80
     keystrokes can be recorded, including Esc-Menu commands.
^E   Execute Macro
^K   Prompts for a number, and then will repeat the next entered key
     that number of times.  ^K cannot be used within a macro, but it can
     be used to execute ^E multiple times.

- MISC OTHER STUFF -

S^Del Delete to end of line
^I   Toggle Insert/Replace mode.
^A   Accept next keypress as literal ATASCII value.  This lets you enter
     Control graphic or international characters that would otherwise be
     treated as editor commands.
^U   Undo line deletes, or changed lines.  Does not undo block operations.
     A handy way to move one or more lines from one place to another, is
     to delete the original lines, move to the destination, and then use
     the Undo operation.
S^(  If a label exists on the current text line, move it up to the previous
     line.  (lines that already contain labels or comments are skipped over)
S^)  Same as above, but moves the label down.
S^[  Move the current line up one position relative to the lines around it.
S^]  Move the current line down one position.
^;   Comments or uncomments a block of text.  You can first mark the start
     of a text block with ^Z, and then press ^; on the last line of the
     block.  If the block does not start with a commented line, then ";"
     characters will be added to the front of all lines in the block.  If
     the block is already commented, then the ";"s will be removed.  If
     you do not set a ^Z block mark first, then this command will process
     only the current line, and move the cursor down.  This can be a
     faster way of commenting just a few lines.
