    This is the 0.2.x release series of Ale, a sequence alignment editor.

        WARNING: The most important thing you need to know is that
this is a *test* release.  It has a few known bugs, and undoubtedly a
lot more unknown ones.  Therefore, you should not use this software on
your only copy of important data -- the program might decide it's
having a bad day and eat your life's work.  We'll feel bad if this
happens, but we won't feel guilty, because we warned you. :-)

        This doesn't mean you can't use it for important alignments.
Just make sure you follow these guidelines:

 1. Before you start working on something, make a safe copy
    of it somewhere.

 2. While working, save early and often.  That way if Ale
    crashes without warning, you'll have lost only the work
    done since the last save.

        Enough said.


USING ALE
-----------

        We assume that you already know the how and why of aligning
sequences.  This manual just discusses how to use Ale to accomplish
those goals.

        (If you have Ale installed on your system already, then
continue reading.  If not, then skip first to the "Installation"
section.)

INVOCATION
----------

        Run ale on a file of sequences like this:

% ale myseqs.gb

        If you have many such files, and want to align them all
together, then start ale like this:

% ale myseqs.gb srprna.embl ...

        You can include as many files as you like, so long as the sum
of their sizes does not exceed eight megabytes.  Ale cannot align
more than 8 megs worth of sequence data at a time, unfortunately.

ALIGNING
--------

        Once ale comes up, it will be displaying a screen that looks
something like this:

------------------------------------------------------------------------------
File  Edit  Display  Movement  Searches  Help  Threats

E.coli       AAAUUGAAGAGUUUGAUCAUGGCUCAGAUUGAACGCUGGCGGCAGGCCUAACACAUGCAAGUCGA
Lcc.cremor   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~nnUUAUUUGAGAGUUUGAUCCUGGCUCAGGACGA
Mc.jannasc   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~AUUCCGGUUGAUCCUGNNGGAGGCC-ACUGC
Mc.vanniel   ~~~~~~~~~~UUUUUUU-----------------AUUCCGGUUGAUCCCGCCGGAGGCU-ACUGC
F.breve      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~NCAAUGGAGAGUUUGAUCCUGGCUCAGGAUNAACGC
Spi.haloph   ~~~~~~NCGUCCCUUCGGGGACGUACAAAAUCAUGGAGAGUUUGAUCCUGGCUCAGAACGAACGC
        [etc...]
------------------------------------------------------------------------------

        There may be more sequences off the bottom of the screen, of
course; it all depends on how many sequences are in the files you're
editing.  And of course, the sequence data extends off to the right
for quite some distance.

        Before we go on, there are some conventions you should be
aware of:

        We use the word "frame" for what is usually called a "window"
So for us, the sentence

   "The application popped up a window, but I iconified it."

        would be written

   "The application popped up a frame, but I iconified it."

        The reason we don't use the word "window" is that it has
another meaning in Ale: a "window" is a rectangular subdivision
within a frame.  Therefore, the illustration above is of a single
frame, with two windows inside it: the ID window and the sequence
window (see below).

        The "ID window" refers to the column of names on the left,
displaying the short IDs for the sequences on the right.  Each ID
should always be lined up with its corresponding sequence.  The
"sequence window" (or "alignment window") is, of course, the window
with the actual sequence data on the right side.

        The words "residue" and "base" are used interchangeably.
"Indels" or "gaps" are any characters which are not residues.

        "point" refers to the position of the text cursor.  This is
different from the mouse pointer.  The text cursor is a little white
box over a character; it starts out in the upper left hand corner of
the alignment.

        "mouse-1" refers to the first (leftmost) mouse button.
Likewise, "mouse-2" is the middle mouse button, "mouse-3" the
rightmost.  

        If your mouse doesn't have 3 buttons, it may be that you can
fake mouse-3 by holding down mouse-1 and mouse-2 simultaneously.  (And
if that doesn't work, I don't know what to say; it's kind of important
that you have three effective mouse buttons to run ale.)

        Throughout the editor, the mouse buttons adhere to the
following conventions:

        * mouse-1 is for moving point, drag-selecting groups of
          sequences or subsequences, and in general doing things
          that affect the display or point, but don't actually
          affect the text of the sequences.  In other words, mouse-1
          is a "safe" mouse button: you can click it somewhere to
          set point, and use it to indicate regions that other
          commands will operate on, but you can't actually change
          any text with it.


        * mouse-2 is the "dangerous" mouse button.  It is used for
          actually moving sequence text.  For example, if you click it
          and hold it down in the middle of a stretch of bases, then
          drag, you'll actually move some of the bases.


        * mouse-3 is a "safe" button.  It usually brings up a menu --
          which menu it brings up depends on where you click it.
          Experiment by pressing mouse-3 while the mouse pointer is in
          different contexts (i.e.: over the ID window, over the
          sequence window... later on, there will be different
          contexts).
                  Not everything on mouse-3's menus will necessarily
          be "safe" -- some of the menu items are operations that do
          affect sequence text, and choosing one of those will change
          what's in the sequence window.  However, merely clicking
          mouse-3, moving the mouse pointer off of the resulting menu,
          and releasing, will never cause anything to happen.


        The menus on the menu-bar can be pulled down with mouse-1,
(although mouse-2 or mouse-3 will work as well).  Take a moment to
explore both those menus and the ones invoked by mouse-3 when clicked
over one of the windows.  However, to avoid accidentally running
anything from the menus while you explore, make sure you move the
mouse pointer entirely off a menu before releasing the button
(releasing the button over a menu entry selects that entry).

        Like the mouse-buttons, the keyboard commands can be divided
into two groups: safe and unsafe (non-destructive and destructive).
The movement commands, which I'll describe first, are all
non-destructive.  A number of these are duplicated in the Movement
Menu, to make things easier for new users, by the way.

        C-f, right-arrow ................ forward position
        C-b, left-arrow ................. backward position
        C-n, down-arrow ................. next line
        C-p, up-arrow ................... previous line

        C-right-arrow ................... forward to next base
        C-left-arrow .................... backward to next base
        M-right-arrow ................... forward to next base group
        M-left-arrow .................... backward to previous base group

        C-M-right-arrow ................. forward screen
        C-M-left-arrow .................. backward screen
        S-M-right-arrow ................. go to last base in sequence
        S-M-left-arrow .................. go to first base in sequence

        C-down-arrow .................... down to base
        C-up-arrow ...................... up to base
        M-down-arrow .................... down to different base
        M-up-arrow ...................... up to different base

        C-M-down-arrow .................. down screen
        C-M-up-arrow .................... up screen
        S-M-down-arrow .................. down to last sequence in window
        S-M-up-arrow .................... up to first sequence in window

        C-o ............................. recenter (and check windows)

        The notation for keys works this way:

        "C-n" means hold down the Control key while you press "n"

        "C-M-right-arrow" means hold down the Control and Meta keys
        while you press right-arrow.  "S-" stands for the Shift key.

          If your keyboard doesn't have a Meta key, look for one
called "Alt", or maybe "Compose Character, or perhaps a key with a
diamond shape on it.  If no key seems to be working as a Meta key,
then you'll probably have to set up a Meta key using the xmodmap
program.  Consult someone experienced with X if you don't know how to
do this yourself.

        You can also move around with the mouse.  Just clicking
mouse-1 at a point will move the text cursor to that spot (be careful
not to drag it, though, or you'll get a different effect!).

        Now for the destructive commands.  The first thing to know is
that the regular printing characters ("A", "B", "C", numbers,
punctuation marks, and special symbols like "&") simply mean
themselves.  That is, typing an "a" inserts an "a" into the sequence
at point (actually, it won't if the sequence is locked to prevent such
insertions, but that's discussed in a later section).

        There are also keyboard and mouse commands specifically for
moving chunks of sequence around.  They are:

        C-r ............................. slide base(s) to the right
        C-l ............................. slide base(s) to the left
        M-r ............................. fetch base from right
        M-l ............................. fetch base from left
        C-M-r ........................... throw base(s) to the right
        C-M-l ........................... throw base(s) to the left

        C-d, delete ..................... delete char in front of point
        Backspace ....................... delete char behind point

        Tab ............................. insert context-sensitive indel (gap).
        M-Tab ........................... insert context-sensitive indel in
                                          all sequences but this one.

        mouse-2 ......................... slide sequence chunks right or left.


        Rather than describing what each of these do in detail, it's
probably best for you to try them out yourself to discover how they
behave.  Make a junk file (we're going to destroy the alignment of the
sequences in it, so be sure it's a copy you don't care about), and run
Ale on it.  Try out all of the commands above.  For mouse-2, the way
to learn about it is to find a contiguous stretch of residues with
gaps on both sides, for example:

   ------------UUUUUUUUUUUUUUUUUUUGGGGGGGGGGGGGGGGGG----------------

        place the mouse pointer somewhere in the middle (say, on the
first "G"), then press and hold mouse-2.  You'll see the two halves
highlight in different colors -- you can drag them right or left
independently.  If you want to drag the whole chunk, then click the
mouse on the first residue in the stretch, or click it just past the
last residue.

LOCKING
-------

        Sequences can be "locked" into one of four different states:

        * "-Locked-": A strictly locked sequence cannot be changed at
                      all.  Not only can no characters be inserted or
                      deleted, but residues can't even be moved around
                      within the sequence.

        * "GapShift": Residues and gaps can be shifted right and left,
                      but the total number and _relative_ positions of
                      residues and gaps cannot be changed.

        * "GapInOut": Gap characters may be inserted or deleted, but
                      residues may not.  Anything that is allowed in
                      GapShift mode is also legal in GapInOut mode.

        * "Unlocked": Everything is allowed.  You can insert or delete
                      gaps or bases, shift them around, do anything.
                      Naturally, anything legal in GapInOut is also
                      legal in Unlocked mode.

        Remember that these locking states are per-sequence.  One
sequence can be Unlocked while the one directly above it is strictly
Locked.

        The most straightforward way to change a sequence's locking
status is with the "Lock Status" window.  To get to this window, pull
down the Display menu and choose "Show Lock Status".  A new window
will appear to the left of the ID window.  The lock states are lined
up with the ID's: you can click on the lock status for each sequence
with mouse-1; repeated clicks cycle through all the possible lock
states (later on, when we get to groups, you'll see how to change the
lock states for many sequences at once).

        You can hide the Lock Status window by pulling down the
Display menu and choosing "Hide Lock Status".

        If displaying the lock window is too much trouble to go
through just to change one sequence, you can pull up the mouse-3 menu
on an individual sequence and choose "Cycle Lock Status" from there.
The menu will have the sequence's ID in the menu title, so you can be
sure of which sequence you're operating on.

GROUPS
------

        Sometimes it's useful to have your commands apply to more
sequences than just the one you're editing.  You can do this by
forming "sequence groups".  Editing commands apply to all the
sequences in a group.  For example, if you insert an indel into
sequence E.coli at position 13, and E.coli is in a group with six
other sequences when you do it, then they will all get a new indel at
position 13.  Here's how to create groups:

        Simply drag the mouse across some of the ID's in the ID
window.  For example, place the mouse on "Lcc.cremor" below (anywhere
on the name, it doesn't matter where) and drag to "Mc.vanniel":

------------------------------------------------------------------------------
File  Edit  Display  Movement  Searches  Help  Threats

E.coli       AAAUUGAAGAGUUUGAUCAUGGCUCAGAUUGAACGCUGGCGGCAGGCCUAACACAUGCAAGUCGA
Lcc.cremor   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~nnUUAUUUGAGAGUUUGAUCCUGGCUCAGGACGA
Foo.bari     ~~~~~~~GAA------------------UUA----UUUGAGAG-UUUGAUCCUGG-UAGGACGA-
Mc.jannasc   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~AUUCCGGUUGAUCCUGNNGGAGGCC-ACUGC
Mc.vanniel   ~~~~~~~~~~UUUUUUU-----------------AUUCCGGUUGAUCCCGCCGGAGGCU-ACUGC
F.breve      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~NCAAUGGAGAGUUUGAUCCUGGCUCAGGAUNAACGC
Spi.haloph   ~~~~~~NCGUCCCUUCGGGGACGUACAAAAUCAUGGAGAGUUUGAUCCUGGCUCAGAACGAACGC
        [etc...]
------------------------------------------------------------------------------

        This will place all the sequences from Lcc.cremor to
Mc.vanniel, inclusive, into one group.  A Group List will pop up in a
separate frame, showing the new group (it will have the name "Unnamed
1").

        "Unnamed 1" is now the "selected group".  You can add more
sequences to it just by clicking on their ID's, or dragging groups of
them (go ahead and add "Spi.haloph" to it by clicking on its ID).

        You can remove sequences from the selected group the same way:
just click and drag.  If the area you clicked in was part of a
selected group, then you'll remove sequences from the group; if it was
not part of the selected group, then you'll add to the selected group
(creating a new selected group if there isn't one right now).

        If you want to create a different group, then click on
"Create New Group" in the Group List.  It will prompt you for a name:
enter a name and hit Return.  Now the new group is selected (even
though it has no sequences yet), and "Unnamed 1" is merely
"displayed".

        The difference between a "displayed" group and a "selected"
one is crucial.  There can be only one selected group at a time, and
being selected means that an editing operation in any one of its
sequences affects all of the sequences.  A selected group is
highlighted more strongly than a merely displayed group.  If two
groups overlap, then they cannot both be displayed at the same time,
nor can one be selected while the other is displayed.

        However, if a group is displayed, you can select it by
clicking on one of its ID's.  Alternately, you could select it by
clicking on its name in the Group List.  A group can be deleted by
clicking on "<delete>" in the Group List.  Deleting a group does not
affect the content of its sequences at all, it just makes the group
itself stop existing.

        The selected group is not only the one that affects editing
operations, it is also the group to which sequences will be added if
you drag in the ID window.  If you create group "Foo", add some
sequences to it, and then create group "Bar", the next ID's you drag
over will be added to "Bar".  You can reselect "Foo" by clicking on
its name in the group buffer.

        It is possible for sequences to be a member of multiple
groups, since only one group is selected at any given moment.  There
is no limit to the number of groups that can be created in a single
editing session.

        The Group List itself can be shown and hidden by choosing the
right entry from the main Display menu, just as with the Lock Status
window.

        Also, if you press mouse-3 over a group in the ID window, you
will get a menu of group operations, some of which duplicate things
offered in the Group List.

        It's probably a good idea to practice a little bit with
groups, creating overlapping groups, selecting different ones, and
adding and removing sequences from them.

SELECTIONS
----------

        You can also operate on rectangular regions of the alignment
window by creating "selections".  Selections are created and operated
on almost entirely with the mouse.  For example, to create one below,
you might press down mouse-1 (and hold it) on the "*" in Lcc.cremor
Lcc.cremor, drag down to the other "*", and release.

------------------------------------------------------------------------------
File  Edit  Display  Movement  Searches  Help  Threats

E.coli       AAAUUGAAGAGUUUGAUCAUGGCUCAGAUUGAACGCUGGCGGCAGGCCUAACACAUGCAAGUCGA
Lcc.cremor   ~~~~~~~~~~~~~~~~~~*~~AAAAAUUU-------UUUGAGAGUUUGAUCCUGGCUCAGGACGA
Foo.bari     ~~~~~~~GAA-----------UUA--GUAUU---------GAG-UUUGAUCCUGG-UAGGACGA-
Mc.jannasc   ~~~~~~~~~~~~~~~~~~~~~G-AUGGC-----------GGUUGAUCCUGNNGGAGGCC-ACUGC
Mc.vanniel   ~~~~~~~~~~~~~~~~~~~~~UUUU-UUU----*------GUUGAUCCCGCCGGAGGCU-ACUGC
F.breve      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~GAGUUUGAUCCUGGCUCAGGAUNAACGC
Spi.haloph   ~~~~~~NCGUCCCUUCGGGGACGUACAAAAUCAUGGAGAGUUUGAUCCUGGCUCAGAACGAACGC
        [etc...]
------------------------------------------------------------------------------

        A selection covering all the residues in between those two
corners will have been created (selections usually ignore outside
bases when they're being created).  Now use mouse-2 to drag that
selection right and left.  Note how it stops when you collide against
the wall of residues on the right.

        Drag it back to near its original position.  Use M-mouse-2
(hold down the Meta key while you press mouse-2) to drag the selection
slowly to the right.  When it hits the wall of residues, it will
collapse gradually into it, and as you slowly drag back the selection
will return to its original configuration.

        Try pressing mouse-3 while over the selection -- a menu of
selection commands should pop-up.  You can "right justify" a selection
(move all of its residues to the right), left justify it, convert it
to upper case, lower case... or just unselect it. :-)

        There's another way to create selections: press S-mouse-1 at
one corner (a red mark will be left there to indicate that corner) and
release the mouse.  Now move to where you want the other corner, by
the most convenient means available, and press mouse-1.  The selection
will be created as before, but with those two points as corners.

        If you just want to mark the two columns bounding a selection,
and have it include all sequences, then use S-mouse-1 on both sides.
For example, if S-mouse-1 had been clicked at both asterisks below,
then the resulting selection would consist of all the upper case
characters:

------------------------------------------------------------------------------
File  Edit  Display  Movement  Searches  Help  Threats

E.coli       aaauugaagaguuugaucAUGGCUCAGAUUGAACgcuggcggcaggccuaacacaugcaagucga
Lcc.cremor   ~~~~~~~~~~~~~~~~~~*~~AAAAAUUU-------uuugagaguuugauccuggcucaggacga
Foo.bari     ~~~~~~~gaa-----------UUA--GUAUU---------gag-uuugauccugg-uaggacga-
Mc.jannasc   ~~~~~~~~~~~~~~~~~~~~~G-AUGGC-----------gguugauccugnnggaggcc-acugc
Mc.vanniel   ~~~~~~~~~~~~~~~~~~~~~UUUU-UUU----*------guugaucccgccggaggcu-acugc
F.breve      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~gaguuugauccuggcucaggaunaacgc
Spi.haloph   ~~~~~~ncgucccuucggGGACGUACAAAAUCAUggagaguuugauccuggcucagaacgaacgc
        [etc...]
------------------------------------------------------------------------------

        Note that it includes the top and bottom sequences, E.coli and
Spi.haloph, even though they are not with in the rectangle marked off
by the two asterisks.  That's because, when S-mouse-1 is used for both
clicks in creating a selection, the two clicks really only mark off
the delimiting columns for a selection which will include all
sequences.

        You can remove a line from a selection by clicking C-mouse-1
on the line, inside the selection.

SAVING YOUR WORK
----------------

        The File menu offers two options: "Save" and "Save As".  If
you choose "Save", then all the changes you've made are saved back to
their respective sequence files.  Suppose you ran Ale on foo.gb and
bar.embl, and made changes to sequences from both files.  When you
"Save", those sequences that came from foo.gb will be written back
into foo.gb (with the new changes), likewise, those from bar.embl will
be saved back to bar.embl.

        "Save As" is a way of creating a new file containing all the
sequences in the alignment window.  When you choose "Save As", you
will be prompted for a new file to save them in.  If the filename you
type in ends in ".gb", then all the sequences will be saved in GenBank
format (no matter what their original, source format was).  If it ends
in ".embl", then they'll be saved in EMBL format, etc.

        After you've done a "Save As", all subsequent "Save"s save to
the new file -- the original source files are forgotten.

        Once again, we highly recommend that you save your sequences
as often as you can while working, to minimize the damage done by a
sudden crash of the editor.  It hasn't crashed much lately, but it
also hasn't been as exposed to very many different environments yet
(you're doing us a favor by testing it out, in fact).

TIPS
----

        Sometimes its possible to get the sequence window and ID
windows out of sync.  If this happens, don't panic -- just type C-o,
which recenters everything and insures that the windows are lined up
properly.  (It's like C-l in native Emacs, if you're familiar with
that).

        If your text cursor somehow winds up in the ID or Lock Status
windows, just click mouse-1 in the sequence window before going on.
Things won't work right if the cursor is in any other window.

INSTALLATION
------------

        If you don't already have a copy of ale, go and get it
from http://www.red-bean.com/ale/.

        You must also have GNU Emacs 22.1 (or a later version)
installed on your system.

        Once you've got the ale tar file, ale-0.2.XY.tar.gz or some
later version, unpack it like this:

        zcat ale-0.2.XY.tar.gz | tar xvf -

        ("zcat" must invoke GNU zip (gzip/gunzip), standard Unix
zcat/uncompress won't do it.  GNU zip is available from
prep.ai.mit.edu:pub/gnu/gzip-<VERSION>.tar.gz, where <VERSION> is the
highest version number you see there.)

        This will create a directory ale-0.2.XY/.  Once it's unpacked,
cd into that directory.  Edit the Makefile in the obvious ways.  If
you are root, and wish to install it in /usr/local/{bin,lib}, then you
won't need to change much.  Otherwise, you should change the PREFIXDIR
variable in the Makefile appropriately.

        It's best to make Ale's PREFIXDIR be the same as the prefix
you used when installing Emacs.

        Once the Makefile is edited, just type "make install" and hope
for the best.

REPORTING BUGS
--------------

        We enthusiastically welcome bug reports (and there are sure to
be some, since this is a test release).  If you think you have found a
bug, choose "Report a Bug" from the Help Menu and tell us about it.
Include as much detail as you can, even things you think can't
possibly be related to the bug -- in order to fix it, we have to be
able to reproduce it.  Documentation bugs are bugs too.

        You can use the same address for suggesting new features.  Of
course, whether we're able to add the feature depends partly on on how
difficult it is to implement and partly on its usefulness to users.
There's already a backlog of useful things we'd like to add, so we
can't make any promises.
