INSTALL

For new UMENU2 users, I recommend the installation method outlined in
the INSTALL.easy document. Once you've had a little experience with the
easy configuration, you'll be in a better position to use a file manager
to move directories and change config locations.

For experienced UMENU2 users who want a non-standard installation, this
document should be of value.

    ==========

In some scratchpad directory somewhere, untar the tarball. Its hierarchy
looks like this:

umenu2
   conf
   prog
   menu
     u

Decide where you want these four directories:

* conf, which is where the program config goes
* menu, which is where the menu hierarchy goes
* prog, which is where the program executables go
* optionally um2, whose job it is to be relative to, usually meaning
  the parent of, one of the the preceding three directories

If you want the conf directory anywhere but ~/umenu2/conf, you must put
its location in ~/.umenurc. For instance, if your username is richard
and you want your conf in /etc/umenu2/richard, then your ~/.umenurc must
look as follows:

conf=/etc/umenu2/richard

So the ~/.umenurc file guides the program to the conf directory. The
conf directory, in turn guides you to the menu directory, the prog
directory, and optionally the um2 directory, whose job is to be relative
to the umenu and prog directories. The conf directory can also contain
some other config info, but this other config info is usually provided
by command line options to ./umenu.py.

The config information in the conf directory is laid out as key-value
pairs, where the key is the filename and the value is the file contents.
So within the conf directory, the file called um2 might contain:

~/um

And in the conf directory the menu file might contain:

:::um2:::/menu

In the preceding, :::um2::: is a token for the location defined in the
conf directory as the um2 location, and is substituted by the program.

Assuming your login is richard and you lay out conf contained files um
and menu as described, umenu.py would resolve the um2 directory to be
/home/richard/um and the menu directory to be /home/richard/um/menu.

Perhaps you want the actual executable files to be in a common area
owned by root, so all users of a certain class get the same menus. This
is easy enough: Within the conf directory, create a file named prog that
contains the following: 

/usr/local/umenu2/bin

NOTE: There is no need for this directory to be on the path and in fact
it's better if it's not. When umenu.py needs to spawn another UMENU2
executable, it knows to do it in this directory.

The prog directory must always have a docs subdirectory which contains
all the text documents such as READMEs and INSTALLs and the like,
including the document you're reading now.

Once you've decided on the directories for (optional) um2, conf, prog
and menu, your final steps are to mkdir all the way down to, but not
including, those directories. Then just use the mv command to move the
tarball's conf, prog, menu, and (optionally) umenu2 directories to the
proper places,  with the proper names.

# EXAMPLE

Your username is richard, and you want the following setup:

prog: /usr/local/umenu2/bin
conf: /home/richard/umenuconf
menu: /home/richard/mymenus

1. Log in as richard
2. Back up then delete any existing directories of the names listed above
3. Back up any existing ~/.umenurc file
4. su -c mkdir /usr/local/umenu2
5. cd /home/richard/temp       (just as an example)
6. tar xzvf umenu-whatever.tgz
7. cd ./umenu2
8. su -c mv prog /usr/local/umenu2/
9. su -Rc chown root.root /usr/local/umenu2
10. mv conf ~/umenuconf
11. mv menu ~/mymenus
12. echo conf=/home/richard/umenuconf > ~/.umenurc
13. cd ~/usr/local/umenu2/bin
14. ./umenu.py u

# SIMPLER ALTERNATIVE
The easier way to install would be to start with the Easy INSTALL method
described in INSTALL.easy. Get used to how things work, and then when
you're ready, change ~/.umenurc and the directories in the conf
directory to reflect how you really want things laid out.

/* vim: set ai tw=72: */
