1. About Arka
2. How to use Arka
3. Config files
4. Problems, bugs, maintainer


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 one. Main scope
of the program is the manipulation and visualisation of DNA / RNA / protein
sequences.

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 GP 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.
Unless, of course, it is a 386 SX.


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

I think I don't have to explain what the 'File' and 'Options' menus do. Just
note that the entry field in a '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!

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 a '%s' where you would put the file's name, for example try to
enter something like that:

wc -l %s

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

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

'Programs' contains a list of the GP package 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. 

Guess what the 'help' menu does, or, rather, should do but doesn't (not yet).


3. Config files.

There is the global config file, /etc/arkarc, and a user directory,
$HOME/.arka/, which contains a config file (configuaration; not yet!),
command_history, file_history 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 run expects a file -- you put a
'%input' and the program will get its file. 

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.

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 one spec files for just any
command-line programs of your choice. 

But beware: if the program is trying to read standard input, arka will hang --
because it waits for the program to finish, and the program is waiting for an
input -- which it doesn't get.


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.

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/.
