Contents:

1. About Arka

2. How to use Arka
 2.1. Arka window
 2.2. Menus
  2.2.1. General
	2.2.2. Shortcut keys
  2.2.3. Edit
  2.2.4. Options
  2.2.5. Tools
  2.2.6. Windows
  2.2.7. Programs

3. Configuration files.
 3.1. Files
 3.2. Spec files for the command-line programs in the `Programs' menu.

4. Problems, bugs, maintainer
 4.1. Bugs
 4.2. Mail me!

=================================================================================

1. About Arka

Arka is a program that (1) serves as a graphical interface for the programs
from the GP package (see http://www.bioinformatics.org/genpak/) and virtually
for any other command line program (2) has some funtions on it's own. The main
scope of the program is the manipulation and visualisation of DNA / RNA /
protein sequences, but arka is a suitable, however humble, interface for
anything from blasta through make to zip.

The GP package contains many command-line utilities which fullfill a whole bunch
of tasks (from DNA sequence searches to restriction analysis and determining the
melting temperature of oligonucleotides). While those programs are convenient to
use in batch processing and CGI scripts (which was the purpose of those
programs), they lack a nice GUI. 

Arka remembers the options for the command-line programs and knows what both the
programs and the options do. Besides, it has some gadgets on its own. It
requires GTK+, but doesn't need GNOME. Also, it is small and quick: look, I
write and use my programs on an old 486 laptop. It should run like hot butter on
your computer.

=================================================================================

2. How to use Arka

2.1. Arka window

The main window of the program consists of three sub-windows. They are called
'input', 'output' and 'error' and correspond to stdin, stdout and stderr. In
other words, 'input' window contains the data which are fed into the used GP
program; when you run the program, it's output is stored in the 'output' window
and any error messages issued are stored in the 'error' window. You can load
just any text file into the 'input' window -- a FASTA formatted sequence, a
matrix, a list of parameters. Anything goes. However, if you run a GP program
and it doesn't find in the input what it expects (for example, gp_gc expects a
DNA / RNA sequence), you will get an error message in the 'error' window.


2.2. Menus

2.2.1. General

I think I don't have to explain what the 'File', 'Options' or 'Help' menus do.
Just note that the entry field in each 'file' dialog is nearly as potent as a bash
commandline: it supports file extension with TAB, ctrl-e, ctrl-a, ctrl-u etc.
Another nice feature of the gtk+ toolkit: in each menu, you see a dashed line on
the top of the menu. This is called a 'tearoff' -- try clicking on it and you
will get a separate 'toolbox' window. This is so much more efficient than
standard toolboxes!


2.2.2. Shortcut keys

You can easily add shortcuts to menu items -- just select a menu item (place the
mouse cursor over it) and press a key or a combo. For example, if you press
"Ctrl-s" when the menu item "Save" is highlited, you will be able to use the
shortcut "Ctrl-s" to access the Save dialog directly. The shortcuts will be
saved in the configuration file ~/.arka/shortcuts automagically upon exit.


2.2.3. Edit

'Clear' clears one of the three main windows (input, output and error).
'External editor' launches either the editor defined in the preferences or
'xterm -e vi', which should work in any case. 'Output=>Input' moves the contents
of the 'output' window to the 'input' window. This is a simple way of piping the
output of one program to another one: first you run the first program, next you
move the contents from input to output, and finally, you run the second program.

In the search / replace dialog box you can use any standard regular expression
(e.g. input 'f.*oo' to match 'faaaaaoo', 'foo' and 'fooooo'). '\n' denotes
newlines, '\t' tabs.

'Sequence editor' is an editor specifically designed for DNA/RNA/protein
sequences. It doesn't have many features yet, but is already useful for me.
You can have many types of data on the input window, and you can edit it
directly or using an external editor; however, for nucleotide sequences there is
a special tool -- the sequence editor, featuring several conveniece tools. You
launch it with the Edit->Sequence editor menu entry; all sequences found on the
input can be edited simultaniously -- just choose the name of the sequence you'd
like to edit from the pop-down list and press ENTER. Note that when you press
"done" the contents of the input window will get overwritten with the sequences.


2.2.4. Options

'Editable' -- normally, you cannot directly edit the input window. 'Hide
tooltips' -- tooltips might be useful on the beginning, but in the longer run,
they are very annoying. Note that this option will get saved upon program exit.
'Font' sets the current font used to draw input / output /error / sequence
editor windows, but doesn't save it as a default. 'Preferences...' allows you to
change and save some global preferences: how many items to save in the file and
command history, whether hide or show the tooltips, default font to use, and
external editor command.


2.2.5. Tools

The 'Tools' menu contain gadgets specific for the Arka program. 'GC graph'
draws a GC contents graph based on the sequences in the 'input' window. This
tool expects FASTA sequences in the 'input' window. '3D graph' draws a
complicated 3D graph (I am very proud on this thing: I have re-invented the
z-buffer). The file to draw should have in each line three tab-separated
numbers: the x,y,z coordinates of the data point to draw; optionally, you can
also place an integer number designating the class of the data point (each class
will be drawn with another color) and a label (string) for that point. Empty
lines or lines starting with a '#' are ignored. Here is an example:

# x	y	z	class	label
1.9	2.0	-1.5	8	some point

'Command...' runs for you any arbitrary command (any program you can run from a
normal command line). It stores the command history in the Arkas configuration
file. You can treat the text contained in the 'input' window just like a normal
file -- just put an '%input' string where you would put the file's name, for
example try to enter something like that:

wc -l %input

...and you will get the number of the lines in the 'input' window.


2.2.6. Windows

'Windows' lets you currently only hide / show the three main windows and even
this doesn't work all to well.


2.2.7. Programs

'Programs' contains a list of the supported command line programs. If you choose
one, you will see a brief summary of what the program does and an entry +
description for each relevant option the program supports. The 'man page' button
will launch 'xterm -e man name', where name is the name of the program you
selected.

Arka will build a command line out of the options you select. Example: you
choose Programs / Unix utilities / text / word count. A dialog pops up, showing
all of the supported options. You click on 'count lines', and then on the
'Launch' button. Now arka will run the wc program, which will count the lines in
your input window. Here is what arka exactly does:

	(i) constructs a command line:
		wc -l %input

	(ii) it stores the 'input' window in a temporary file
	
	(iii) substitutes the '%input' in the command line with the name of the
	temporary file

	(iv) runs the program. During the execution of the command line program, a
	dialog box pops up with an 'abort' button -- which, when pressed, kills the
	command line program (so that if the program hangs, you can gracefully quit
	it).

	(v) puts the output of the command line program into the 'output' window, and
	any error messages issued during execution into the 'error' window.

	(vi) stores the command in the command line history.

=================================================================================

3. Configuration files.

3.1. Files

There is the global config file, /etc/arkarc, and a user directory,
$HOME/.arka/, which contains a config file (configuaration),
command_history, file_history, shortcuts with the shortcuts you have created and
(possibly) a file called `programs'.

The trick arka uses to do its work is as follows: arka stores the input window
in a temporary file, and then passes the name of this temporary file to the
program it runs. To be more specific, it builds the command line from the
options and arguments shown in the dialog box, and replaces each string of the
following form:

%input

...with the name of the temporary file. So, wherever you'd like to put the
contents of your input window, and the program you run expects a file -- you put
an '%input', and the program will get its file. For example, say you want to
count lines in the input window using the standard unix program wc. You'd then
put something like that on in the command line:

wc -l %input

or

cat %input | wc -l

While running the program, arka catches its stdout into another temporary file,
and dumps its contents to the 'output' window. The stderr gets caught into yet
another temp file, and dumped to 'error' window.


3.2. Spec files for the command-line programs in the `Programs' menu.

How does arka know how to run a program? The answer is -- it reads its detailed
descriptions stored in one of the two files, /etc/arkarc (take a look at it),
and $HOME/.arka/programs. You can write your own spec files for just any
command-line programs of your choice or create it with the dialog 'Create...'
from the 'Programs' menu (it will get stored in the ~/.arka/programs file).

Editing and creating spec files should be easy using the 'Edit...' and 'New...'
dialogs from the 'Programs' menu. If you find those dialogs confusing, mail me
and tell me why. I sincerly hope that they are self-explanatory. One note only:
if you edit a program, the description will be saved in your local program
specs file, $HOME/.arka/programs, and not the global one.

=================================================================================

4. Problems, bugs, maintainer

4.1. Bugs.

I'm sure there are numerous, but I try to fix anything I find. There are two
problems I am aware at the moment. First, the text windows are not horizontally
scrollable. This is not a problem of Arka, but of the gtk_text widget. The
second problem is what I think is a serious memory leak in graph.c. I will fix
it. Some day. Besides, don't use Arka when you are logged in as root. 

There might be some problems with some of the programs from the FASTA package. I
did not test them all, and FASTA programs as a default run in an interactive
mode. They do have options for non-interactive mode, however, and I should make
sure that they do use them. The most important ones (fasta, fastx, tfasta etc.)
should run fine. Unfortunately, randseq, when run in a non-interactive mode,
does not feed the output to stdout, so currently arka cannot support it.

4.2. Mail me!

I wonder whether these tools will be useful to anyone but me. On the other hand,
they are useful for me (I wrote Arka because I couldn't remember all the
options of the programs I wrote, and because I needed the 3D graph part to
visualise DNA structures). So, whether you like the program or not, please do
mail me (like, to save me the effort of writing another README file). My address
is january@bioinformatics.org; programs homepage is
http://www.bioinformatics.org/genpak/.
