                       AE -- Another Editor
                           Version 1.7

                          User's manual




Why Another Editor?
-------------------

  There are already so many editors for MS-DOS, why take the
  trouble to re-invent the wheel? Well, I couldn't find an
  editor that suited my needs. I wanted one that:

  - could do simple ASCII editing, for writing programs and
  small texts.

  - had user-definable keyboard macros, in case I had some
  repetitive editing to do.

  - was small, so that it could be run from floppy.

  - was efficient: the most important actions, like cursor
  movement and cutting/pasting must be done with a single
  keystroke.

  The result is AE. If you are an unexperienced PC user, then
  read on. I hope that this manual will explain enough to let
  you use AE effectively. If you are already familiar with other
  editors like the Norton editor or Borland's Turbo editors, you
  should have little trouble getting started with AE. You can
  get a list of AE's commands by pressing the F1 key. However,
  some of the details may not be immediately clear. Below, you
  will find a point-by point discussion of these.


1. Entrance and exit
--------------------

  The editor is started by typing "AE" on the DOS command line.
  (If you hadn't guessed!) Alternatively, you can start editing
  an existing file by giving the filename as an argument (see
  also the section "Loading and saving files" below).

  At any point during editing, when you are giving a command but
  have changed your mind, you can press the Escape key to exit.
  The command will not be executed, and AE will return to its
  normal state. Escape does not terminate the program. To do
  this, you must use the exit command Alt-X.


2. Loading and saving files
---------------------------

  You can load a file into AE either by typing it as an argument
  on the command line when starting (e.g. 'AE MYFILE.TXT'), or
  by pressing F3 once AE is running.

  AE can handle filenames with wildcards. If the filename you
  enter contains a '?' (for any single character) or a '*' (for
  any series of characters), then you will get on your screen a
  list with the names of all files that match the wildcard
  pattern. So, if you want to choose from all files in the
  current directory, try to load '*.*'. In the list, you can
  move a selection bar with the 'up' and 'down' keys, or PgUp
  and PgDn. You can also select a file from the file list by
  pressing the first letter of its name. For instance, if you
  press the "A" key repeatedly, the selection bar will step
  through all the file names beginning with an A. When you have
  selected the file you want, press Enter to load it.

  At the bottom of the file list you will find the directories
  that the current directory is connected to. Directory names
  are indicated by a preceding "". If you press Enter with the
  selection bar on a directory, AE scans that directory and show
  you a new file list. In this way you can search the whole disk
  for the file you want.

  The name of the file to be loaded can also be retrieved from
  the history of file names (see the section "Histories", below).

  It is also possible to read the contents of another file and
  add them to the current one. This is the 'INSERT FILE'
  option. You can use it by pressing Shift-F3.

  Saving a file can be done by pressing F2. If the file does not
  have a name yet, AE asks you to give it one. The name of the
  file you are editing can be seen on the statusline. If you
  want to store your file with a different name, then you should
  use Shift-F2. You will then be asked to enter the new filename.

  AE will notice if you have changed a file. You can also see
  this by the asterisk beside the filename on the statusline. If
  you have made changes and try to load another file without
  saving the old one first, AE notifies you and asks if the
  old file should be saved first. The same goes if you try to
  quit the program without having saved your file.


3. Cursor movement
------------------

  The keys to move the cursor are the same as in just about
  every other editor for MS-DOS:

  up, down, left, right:   move one position in that direction
  Ctrl-left, Ctrl-right:   go to start of previous/next word
  Home, End:               go to begin/end of the current line
  Ctrl-Home, Ctrl-End:     go to first/last line on the screen
  PgUp,PgDn:               move one screenful up/down
  Ctrl-PgUp, Ctrl-PgDn:    go to begin/end of file


4. Typing characters and deleting them
--------------------------------------

  This is, again, very much like other editors. When you type in
  a character, it will either be inserted into the text, or it
  will replace the character under the cursor. This depends on
  the mode, which is either 'Insert' or 'Overwrite'. You can
  switch between these modes by pressing the Ins key. The
  current mode is shown on the statusline .

  To remove a character you can either use the Backspace or the
  Delete key. The latter removes the character under the
  cursor, the former removes the one directly left to it. There
  also are commands to remove more than one character at a time:
  Delete line (Alt-L) deletes the current line, delete word
  forward (Alt-W) deletes text from the cursor to the beginning
  of the next word. (Words can be separated by spaces or any of
  the characters : ; , or.)

  For some commands you are asked to enter some text (like a
  name of a file to load, or a string to search for). The text
  appears on the bottom line of the screen, temporarily replacing
  the statusline. Keys that work here usually have the same effect
  as in normal typing: left, right, Ctrl-left, Ctrl-right, Home,
  End, Delete, Backspace, Alt-W, Alt-L and Insert. A peculiarity
  is that if the first key you press is a character key, the text
  that was present will be erased. If you start with any other
  key, the existing text is modified. When you have finished your
  input, you can press Enter to proceed. (In some cases, the up
  and down arrow keys also have a function; see the section
  "Histories".)


5. Cutting and pasting
----------------------

  The keys mentioned so far may be fine to add and remove a
  couple of characters, but to handle larger pieces of text you
  need to cut and paste. The first step for this is to move the
  cursor to one end of the piece of text, and then place a mark
  with the F5 key. The mark itself is not shown, but when you
  move the cursor away from the mark, the piece between the mark
  and the cursor is highlighted. This is called the block.

  You can delete the block (with Shift-F6), copy it to the paste
  buffer (with F7), or cut it (with F6). The difference between
  cut and copy is that cutting the block removes it from your
  text, while copy makes no changes in the text. Unless you have
  chosen to delete, the contents of the block are now stored in
  the paste buffer. You can insert the contents of the paste
  buffer into a different part of the text, or into the text in
  a different window. Move the cursor to the position where you
  want to insert it, then press F8. Pasting does not change the
  paste buffer, so pressing F8 more than once inserts
  multiple copies of the block.

  If you don't want to do anything with the block you can remove
  the mark with Shift-F5.

  The last option to be mentioned is the possibility to compare
  the block to the paste buffer. This can be handy if you want
  to check whether two pieces of text are completely equal or
  not. After cutting or copying the first piece, select the
  second piece, then press Shift-F7. The result is shown on the
  statusline.


6. Searching and replacing text
-------------------------------

  You can search for a sequence of characters in the text and,
  optionally, replace it by another. These commands are started
  with F4 and Shift-F4 respectively. You will first be asked to
  enter the text to look for, the text to replace it with (if
  you have pressed Shift-F4), and the search options.

  Possible search options are R, I, N and W. The R option means
  reverse search. Normally the search will be from the cursor
  position forward. The I option tells AE to ignore the case of
  the characters, so that an uppercase "A" will be equal to a
  lowercase "a", etc. The N option is only valid for replacing,
  and stands for "no query". If you leave out the N option, AE
  will move the cursor to the next occurrence of the search
  text, show it and ask you if it should be replaced. You can
  then press Y or N, or Escape to stop. Unqueried replace will
  automatically scan the whole text from the cursor onwards, and
  replace every occurrence of the search text. The W option,
  finally, sets the search for whole words only. This means that
  the search is only successful if a found string is surrounded
  by word-separating characters (e.g. space, comma, period).

  Pressing Alt-R repeats the last search or find & replace
  operation.

  There are other ways to enter the sequence that must be
  searched for:

  * Use the history of search strings (see the section
  "Histories", below).

  * Select a block so that it contains the text you want to
  find, then start the search with F4 or Shift-F4. You will see
  that the search text has already been filled in. In this way you
  can look for other occurrences of, say, a word.

  One more thing: if you want to search for a "new line"
  character, i.e. a CarriageReturn-LineFeed combination, you
  can press Ctrl-Enter. (Just the Enter key won't do,
  because this is used to end your input.)


7. Multiple files
-----------------

  In AE you can edit several files at the same time. You can
  view them in 'windows'. There are three windows, indicated by
  the letter A, B or C on the left of the statusline. Mind you,
  you can only view one window at a time; it takes up the whole
  screen. Switching between windows is done with F9 or Shift-F9
  (the latter switches in reverse direction). Alt-A switches to
  the first window.


8. Keyboard macros
------------------

  You can define 10 keyboard macros. To define a macro, press
  Alt-D. You will be asked for the number of the macro you want
  to define. After that, AE will record every key you press.
  Definition is ended by pressing Alt-D once more. (The
  definition mode is indicated by 'Def' on the statusline.) Now
  you can replay macro number 1 with Alt-1, number 2 with Alt-2,
  and so on to number 10 with Alt-0. AE will act just as if you
  had typed the whole series of keystrokes again. You can replay
  a macro while defining another one, so you can make it a
  powerful tool for repetitive tasks.

  As a small example, the following sequence of keys defines a
  macro that deletes all text from the cursor to the end of the
  current line:

  <Alt-D> <1> <Enter> <F5> <End> <Shift-F6> <Alt-D>

  Note: The occurrence of errors (like searching for a string
  that doesn't exist) will terminate macro execution. Macro
  execution does not work when you are entering DOS commands.


9. Setup
--------

  You can set several preferences for working with AE. These
  preferences can be set by pressing Shift-F1. On the statusline
  you will then see a menu containing the options you can set.
  They are listed below:

    Display     : Controls for the appearance of text on the
                  screen.
      Colors             : Sets the color of normal text, block and
                           statusline. Selecting this option
                           will cycle through several predefined
                           colour combinations. (Note: if your
                           computer has a monochrome video card, 
                           there are only two combinations.)
      cursorType         : Sets the shape of the cursor.
      Fastredraw         : When on, this option causes AE to
                           redraw only a part of the screen if
                           there is more work to be done (key
                           presses to be processed). This makes
                           the screen update less "shaky" on
                           slower PCs.
      Dots-for-spaces    : If this switch is on, spaces in the
                           text will be displayed as small dots.

    Environment : Miscellaneous options.
      Keyclick           : If on, produces an audible click when
                           a key is pressed.
      Bell               : Normally, when AE reports an error,
                           you will hear a beep. This can be
                           switched off.
      Wordwrap           : See the section "Formatting text".
      Tabs               : See the section "Tabs".
      Autoindent         : See the section "Formatting text".
      Insert             : Toggles between insert and overwrite
                           mode (see also the section "Typing
                           characters and deleting them")

    File        : Several options to control the saving of files.
      Exit-auto-save     : If this switch is on, AE will
                           automatically save a changed file on
                           exiting the program.
      Interval-auto-save : AE can periodically save your file.
                           With this option you can set the
                           interval. (When 0, the option is off.)
      Backup-files       : When on, AE will rename the old copy
                           of your file before saving the new
                           version. The backup will have thew
                           extension "BAK".
      Workfile           : See the section on "Workfile", below.

    Printer     : Options to control the printing of your text.
                  See the section "Printing text".

    Save-setup  : Save the setup to a file (explained below).

  To select an option in the setup, press the capital letter in
  its name. So, to change the display colors, press Shift-F1
  followed by "D" and "C", to set the tab spacing Shift-F1 plus
  "E" and "T", and so on. You can also select an option by
  moving the selection bar with the arrow keys, and then
  pressing Enter.

  When you set a switch option (one that can be on or off), you
  will see a question on the screen followed by "Yes" or "No".
  You can change the setting in two ways: by pressing the "Y" or
  "N" key directly, or by pressing the spacebar until it is set
  as you want it and then pressing Enter.

  Every option that can be set with Shift-F1 is included in the
  setup. You can save this setup. AE will store it as 'AE.CFG'
  in the directory of your choice (defaults to the current 
  directory).

  When AE is started, it searches for AE.CFG in the current
  directory. If it doesn't find the setup file there, it 
  searches the directory where the program itself (AE.EXE) is
  located. If this directory doesn't contain one either, it will
  use a default setup. This gives you the possibility to store
  several setup files in different directories. For example, you
  can store a setup for editing programs in C:\PROGRAMS, and store
  a different setup for writing letters in C:\TEXT. If you have
  stored AE.EXE in C:\UTIL then you can put a general purpose
  setup in that directory.

  The keyboard macros are also included in the setup file.


10. Printing text
-----------------

  AE offers the possibility to print the text you are editing.
  You can either print the whole text (with Alt-P) or just the
  selected block (with Shift-F8).

  A couple of options are provided to get your text on the right
  spot on the paper. They are accessible by Shift-F1 P. If you
  set the page length to, say, 60, then AE will send a form feed
  to the printer after every 60 lines of text. Page numbers can
  be added. The top margin is the number of blank lines that is
  inserted at the beginning of every new page. The left margin
  is the number of spaces on the left of each printed line.

  Page breaks can be inserted by typing Ctrl-L (a.k.a. form
  feed character). This will appear in the text, but when
  printed it will cause the printer to advance the paper to the
  top of the next page.

  One last option is the "eject printer page" command. If you
  press Alt-E, AE will send a form feed to the printer, so that
  it will feed the paper to the next page.


11. MS-DOS commands
-------------------

  You can interrupt editing to give a couple of DOS commands by
  pressing F10. AE will then start a DOS shell. To return to AE
  afterwards, type the command "exit" on the DOS command line.

  During these commands, AE will remain in memory, so there will
  be only about 200 to 300 kilobytes left, which is not enough
  to run large programs.

  Note: To start a DOS shell, AE reads the environment variable
  COMSPEC. This variable indicates the directory and name of the
  command interpreter that must be started to process your
  commands. If COMSPEC is not set, you will get an error message
  (COMMAND.COM not found). As a remedy, type the DOS command

  "SET COMSPEC=C:\COMMAND.COM"

  (or something similar, depending on where you have stored
  COMMAND.COM), before you start AE.


12. Formatting text
-------------------

  With AE you can create a text with left and right margins like
  the one you are now reading, by using autoindent and word
  wrap. If autoindent is on and you press Enter, AE will insert
  not only a new line, but also the same number of spaces that
  the previous line starts with. You can switch autoindent on
  and off in the setup (Shift-F1 E A).

  If word wrap is on, AE will truncate the lines you type when
  they have reached a certain length, and proceed on a new line.
  In this way, your text will be formatted as you type. However,
  if you insert text in the middle of a line, its length may
  exceed the wrap length. AE does not look ahead to check. To
  reformat, press Alt-F. Note that this command reformats the
  whole paragraph, i.e. it goes on until it encounters the next
  blank line. You can set the line length for word wrap in the
  setup (Shift-F1 E W L). A line length of 0 means word wrap is
  off. On the statusline you can see if autoindent and word wrap
  are switched on.

  Word wrapping can be done automatically if the corresponding
  setup switch is on (Shift-F1 E W A). This causes AE to reformat
  the current paragraph each time characters are inserted or
  deleted.

  There are two more commands to format text: Alt-C will center
  the current line (e.g. for titles) and Alt-J will justify it
  to the right margin. These, too, only work if word wrap is on.


13. Saving positions
--------------------

  AE can store the current cursor position, to restore it later.
  This can be handy especially if you are programming a keyboard
  macro, or jumping to and fro in a text. The positions are
  saved last-in-first-out, meaning that the position that is
  restored is the one that was last saved. Saving a position is
  done with Alt-S, restoring a saved position with Alt-G.


14. Tabs
--------

  Pressing the Tab key will move the cursor to the next tab
  stop, and Shift-Tab will move to the previous one. AE knows
  two ways to position tab stops: fixed-distance and aligned. If
  the tabs are aligned, AE will look on the line above for the
  next (or previous) beginning of a word. When you press the Tab
  key, the cursor will move to the position just below the
  beginning of that word. In that way you can get your text
  lined up neatly. With fixed-distance tab stops, the cursor
  will move to a certain column number. If you have set the tab
  spacing to, e.g. 8, then the tab stops will be on column 1, 9,
  17, 25 and so on.

  If AE is in insert mode, moving to the next tab stop causes
  spaces to be inserted in the text. When in overwrite mode, AE
  only moves the cursor.

  You can set the tab spacing in the setup. A tab spacing of 0
  means aligned tabs.


15. Special characters
----------------------

  Special characters are those that are not present as normal
  keys on the keyboard. There are control characters, characters
  for foreign languages and graphical characters to make frames
  and the like. AE offers a couple of ways to insert them into
  your text.

  The ASCII table command (Alt-I) displays a table with the full
  IBM character set. You can choose from this table by moving
  the cursor to the desired character and pressing Enter. If
  you know the ASCII value of the character you want, you can
  also enter it by typing its number on the numerical keypad
  while holding down the Alt key.

  Control characters are the characters with ASCII value between
  0 and 31. You can enter control characters directly from the
  keyboard as Ctrl-A, Ctrl-B, etc. All control characters will
  be visible in your text, except for Ctrl-J, which is the line
  separator. (Note: On screen, the combination Ctrl-M + Ctrl-J,
  which is the standard line separator in MS-DOS, is
  indistinguishable from a Ctrl-J alone. Some other operating
  systems, like Unix, use only a Ctrl-J.)

  Warning: Be careful with the Ctrl-Z character (ASCII value
  26). In MS-DOS, it serves as the end-of-file character for
  text files. If you save a file containing this character, all
  text following it will be ignored, next time the file is read.
  Although AE will ask you if the text after the end-of-file
  character should be ignored, some other programs do not. You
  might lose a large part of your text.


16. Histories
-------------

  The names of the files that you load, and the strings that you
  search for, are stored in histories. You can recall these
  later, to save you some typing.

  If you are familiar with command line editors (like CED),
  using the histories will be no problem for you. When you are
  asked to enter a file name to load, or a string to search, you
  can use the up and down keys to go through the history. The up
  key recalls the previous entry in the history, the down key
  gives you the next one.


17. Workfile
------------

  If you do a lot of editing, it is handy when you can store the
  state of your work when exiting the editor. Then, when you
  restart, you can go on working with the file and on the
  position where you were last time. AE is able to store this
  information, in the workfile.

  If the appropriate setup option is on (Shift-F1 F W), AE will
  store the names of the files that were loaded, and their
  cursor position, into a file named AE.WRK. Later, when AE is
  started again, it will read the workfile, and automatically
  load the files in it, with the cursor in the right position.
  However, this is not done when you start AE with a file name
  as argument.


18. Miscellaneous
-----------------

  Below you will find a list with the commands that have not
  been mentioned so far.

  * Match brackets (Alt-M). If the cursor is placed at a bracket
  and Alt-M is pressed, AE will search for the corresponding
  bracket. The search is forward when started at a left
  (opening) bracket, and backward when at a right (closing)
  bracket.

  * New (Alt-N). Clears the file buffer, i.e. it deletes the
  text that is loaded, so you can start working on a new file.
  If the old text has been changed, you will be asked if you
  want to save it first.

  * Editor status (Alt-Q). Shows the names of the files
  currently loaded, and the size of its contents.

  * Toggle case (Alt-T). Reverses the case of the characters in
  the currently selected block. If no block is selected, the
  character under the cursor is changed.

  * Convert to upper case (Alt-U). Like Alt-T, but changes the
  characters to uppercase.

  * Show version number (Alt-Z). Shows the version number and
  date of the copy of AE that you are using.


19. The SPLIT and MERGE utilities
---------------------------------

  AE can only handle files that are smaller than 64 kilobytes
  (65536 bytes). In most cases this will be enough. However, if
  you have to edit a file that is larger, there is a way to get
  around this restriction. You can first split your file in
  several parts, edit the parts, and then glue them together
  again. The SPLIT and MERGE utilities are provided for this.
  They can be called from the DOS command line as follows:

  SPLIT <filename> [<chunksize> [k|l]]

  Splits the file <filename> into smaller chunks. You can give
  the size of the chunks in bytes, kilobytes or lines
  (respectively as a number, or a number followed by "k" or
  "l"). If you don't enter a chunksize, a default of 60
  kilobytes will be taken. If the chunksize is given in bytes or
  kilobytes, it is only approximate, because the program tries
  to split the file at the end of a line. But you will never get
  chunks larger than the given size, unless the file contains
  very very long lines.

  MERGE <part-1> [<part-2> ... <part-n>] <filename>

  Reads the files <part-1>, <part-2> and so on to <part-n> and
  puts their contents in a big file <filename>. The names of the
  parts can contain wildcards ("?" or "*"). The files whose
  names satisfy the wildcard pattern are read in the same order
  as they appear in a directory listing.

  As an example, suppose you have a large file MYFILE.TXT of 150
  kilobytes. The command

  SPLIT MYFILE.TXT 50k

  generates three smaller files MYFILE.000, MYFILE.001 and
  MYFILE.002 of (about) 50 kilobytes each, which you can edit
  with AE. When you have finished editing, you enter the command

  MERGE MYFILE.000 MYFILE.001 NEWFILE.TXT

  or

  MERGE MYFILE.00? NEWFILE.TXT

  and you will get a new file NEWFILE.TXT containing the edited
  contents of the parts.

